✨ Serve the PageTop guides with pagetop-mdbook
Rebuild the website on the current PageTop API, with Bootsier as its
theme and edition 2024. Add the first Spanish guide (doc/v0.6/es) as an
mdBook book, built in build.rs and served with pagetop-mdbook, and the
/doc/latest/{lang} redirect.
Add `tools/doccheck.sh` to check the links of the guides and to compile,
run and test their examples against PageTop.
Move the configuration to config/common.toml and translate the README
to English.
This commit is contained in:
parent
e41e71cc78
commit
1a41a456d4
80 changed files with 14112 additions and 1218 deletions
193
doc/v0.6/es/src/how-to/themes.md
Normal file
193
doc/v0.6/es/src/how-to/themes.md
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
# Crear un tema
|
||||
|
||||
**Objetivo:** elegir el aspecto de la aplicación y, si hace falta, crear un tema propio que herede
|
||||
de otro y cambie sólo lo necesario.
|
||||
|
||||
El tema es la **piel** de la aplicación: maqueta la página por regiones, aporta estilos y
|
||||
*scripts*, y decide cómo se ve cada componente. Cambiar de tema no obliga a tocar las páginas.
|
||||
|
||||
## 1. Elige un tema
|
||||
|
||||
PageTop trae el tema `Basic`. Hay otros como extensiones:
|
||||
|
||||
| Tema | *Crate* | Estilo |
|
||||
|---|---|---|
|
||||
| Basic | `pagetop` | Sobrio, sin dependencias |
|
||||
| Bootsier | `pagetop-bootsier` | [Bootstrap 5](https://getbootstrap.com) |
|
||||
| Aliner | `pagetop-aliner` | Muestra la estructura de la página, para pruebas |
|
||||
|
||||
Para usar uno, declara su extensión como dependencia y selecciónalo en la configuración:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
pub struct MyApp;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for MyApp {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_bootsier::Bootsier]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```toml
|
||||
[app]
|
||||
theme = "Bootsier"
|
||||
```
|
||||
|
||||
Si el tema configurado no está disponible, PageTop usa `Basic` y avisa al arrancar.
|
||||
|
||||
## 2. Crea un tema
|
||||
|
||||
Un tema es una extensión que además implementa `Theme`. Todos los métodos de `Theme` tienen
|
||||
implementación por defecto, así que el mínimo es éste:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
pub struct Earth;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Earth {
|
||||
fn theme(&self) -> Option<ThemeRef> {
|
||||
Some(&Self)
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Theme for Earth {}
|
||||
```
|
||||
|
||||
## 3. Hereda de otro tema
|
||||
|
||||
Lo más práctico es partir de un tema existente y cambiar sólo lo necesario. Un **tema hijo**
|
||||
hereda todo de su padre:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
pub struct Earth;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Earth {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_bootsier::Bootsier]
|
||||
}
|
||||
|
||||
fn theme(&self) -> Option<ThemeRef> {
|
||||
Some(&Self)
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Theme for Earth {
|
||||
fn parent(&self) -> Option<ThemeRef> {
|
||||
Some(&pagetop_bootsier::Bootsier)
|
||||
}
|
||||
|
||||
// Adds its own style sheet to every page.
|
||||
fn before_render_page_body(&self, page: &mut Page) {
|
||||
if let Some(parent) = self.parent() {
|
||||
parent.before_render_page_body(page);
|
||||
}
|
||||
page.alter_assets(StyleSheet::from("/static/css/earth.css").with_weight(10));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`before_render_page_body()` es donde un tema añade sus recursos. Al sobrescribirlo, llama al del
|
||||
padre para no perder los suyos.
|
||||
|
||||
No olvides seleccionarlo en la configuración (`theme = "Earth"`) y declararlo como dependencia
|
||||
de la aplicación.
|
||||
|
||||
## 4. Ajusta componentes
|
||||
|
||||
`setup_component()` permite retocar cualquier componente antes de pintarlo. La macro
|
||||
`setup_component!` lo distingue por tipo:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# pub struct Earth;
|
||||
# #[async_trait]
|
||||
# impl Extension for Earth {}
|
||||
#[async_trait]
|
||||
impl Theme for Earth {
|
||||
fn setup_component(&self, component: &mut dyn Component, _cx: &mut Context) {
|
||||
setup_component!(component, {
|
||||
Button => |button| { button.alter_prop(PropsOp::add_classes("earth-button")); },
|
||||
Block => |block| { block.alter_prop(PropsOp::add_classes("earth-block")); },
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Reescribe componentes
|
||||
|
||||
Para cambiar el HTML entero de un componente, usa `render_component()` con la macro
|
||||
`render_component!`. Lo que no captures se pinta como siempre:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# pub struct Earth;
|
||||
# #[async_trait]
|
||||
# impl Extension for Earth {}
|
||||
#[async_trait]
|
||||
impl Theme for Earth {
|
||||
async fn render_component(
|
||||
&self,
|
||||
component: &dyn Component,
|
||||
cx: &mut Context,
|
||||
) -> Option<Result<Markup, ComponentError>> {
|
||||
render_component!(component, {
|
||||
Badge => |badge| Ok(html! {
|
||||
span class="earth-label" { (badge.label().using(cx)) }
|
||||
}),
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Como el componente expone sus datos con *getters* (`badge.label()`), el tema no depende de sus
|
||||
detalles internos.
|
||||
|
||||
## 6. Cambia las páginas de error
|
||||
|
||||
Las páginas 403, 404 y de error grave se pintan con la plantilla activa, para no perder la
|
||||
navegación. Un tema puede cambiar su contenido:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# pub struct Earth;
|
||||
# #[async_trait]
|
||||
# impl Extension for Earth {}
|
||||
#[async_trait]
|
||||
impl Theme for Earth {
|
||||
fn error_404(&self, page: &mut Page) {
|
||||
page.alter_title(Lc::n("Not found")).alter_child_in(
|
||||
&CoreRegions::Content,
|
||||
ChildOp::Prepend(
|
||||
Html::with(|_| {
|
||||
html! {
|
||||
h1 { "This page has gone off to plant tomatoes" }
|
||||
p { a href="/" { "Back to home" } }
|
||||
}
|
||||
})
|
||||
.into(),
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Más allá
|
||||
|
||||
Un tema también puede definir **regiones** y **plantillas** propias, fijar los anchos de los
|
||||
puntos de corte (`breakpoint_entry()`) o traducir las intenciones a su paleta de colores
|
||||
(`intent_color()`). La documentación del módulo `core::theme` en
|
||||
[docs.rs](https://docs.rs/pagetop) recorre los seis pasos para personalizar un tema por completo.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Intervenir con acciones](actions.md): retocar componentes desde una extensión que no es un tema.
|
||||
- [Componentes, temas y renderizado](../explanation/rendering.md).
|
||||
Loading…
Add table
Add a link
Reference in a new issue