Compare commits
4 commits
6a2bb91dcc
...
f42f5e9b89
| Author | SHA1 | Date | |
|---|---|---|---|
| f42f5e9b89 | |||
| 4e007feec8 | |||
| 1a41a456d4 | |||
| e41e71cc78 |
84 changed files with 16044 additions and 1218 deletions
34
.gitignore
vendored
34
.gitignore
vendored
|
|
@ -1,10 +1,28 @@
|
|||
# Ignora directorios de compilación
|
||||
**/target
|
||||
# Build directories
|
||||
target/
|
||||
|
||||
# Archivos de log
|
||||
**/log/*.log*
|
||||
# Log files
|
||||
log/
|
||||
|
||||
# Archivos de configuración locales
|
||||
**/local.*.toml
|
||||
**/local.toml
|
||||
.env
|
||||
# Local configuration files
|
||||
.cargo
|
||||
.claude
|
||||
.vscode
|
||||
config/local.*.toml
|
||||
config/local.toml
|
||||
|
||||
# Books built by mdBook from doc/ (see build.rs)
|
||||
static/
|
||||
|
||||
# System files and work directory
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
workdir/
|
||||
|
||||
# Note: Cargo.lock is NOT ignored. This project contains binaries, so Cargo.lock
|
||||
# must be versioned for reproducibility.
|
||||
|
||||
# Generated by tools/doccheck.sh
|
||||
tools/doccheck/examples/
|
||||
tools/doccheck/tests/generated_*.rs
|
||||
tools/doccheck/Cargo.lock
|
||||
|
|
|
|||
1617
Cargo.lock
generated
1617
Cargo.lock
generated
File diff suppressed because it is too large
Load diff
42
Cargo.toml
42
Cargo.toml
|
|
@ -1,17 +1,33 @@
|
|||
[package]
|
||||
name = "pagetop-website"
|
||||
version = "0.0.1"
|
||||
edition = "2024"
|
||||
description = "Official PageTop website, to introduce this development environment to the community."
|
||||
publish = false
|
||||
repository = "https://git.cillero.es/manuelcillero/pagetop-website"
|
||||
homepage = "https://pagetop.cillero.es"
|
||||
license = "MIT OR Apache-2.0"
|
||||
authors = ["Manuel Cillero <manuel@cillero.es>"]
|
||||
|
||||
[[bin]]
|
||||
name = "pagetop-website"
|
||||
version = "0.0.1"
|
||||
edition = "2021"
|
||||
|
||||
description = """
|
||||
Web oficial de PageTop para introducir este entorno de desarrollo a la comunidad.
|
||||
"""
|
||||
publish = false
|
||||
|
||||
repository = "https://git.cillero.es/manuelcillero/pagetop-website"
|
||||
homepage = "https://pagetop.cillero.es"
|
||||
license = "MIT OR Apache-2.0"
|
||||
authors = ["Manuel Cillero <manuel@cillero.es>"]
|
||||
path = "src/main.rs"
|
||||
|
||||
[dependencies]
|
||||
pagetop = { version = "0.1", path = "../pagetop" }
|
||||
pagetop = { path = "../pagetop" }
|
||||
pagetop-bootsier = { path = "../pagetop/extensions/pagetop-bootsier" }
|
||||
pagetop-mdbook = { path = "../pagetop-mdbook" }
|
||||
|
||||
[build-dependencies]
|
||||
pagetop-mdbook = { path = "../pagetop-mdbook" }
|
||||
|
||||
[profile.dev]
|
||||
opt-level = 0
|
||||
debug = true
|
||||
split-debuginfo = "unpacked"
|
||||
|
||||
[profile.release]
|
||||
opt-level = 3
|
||||
lto = "fat"
|
||||
codegen-units = 1
|
||||
strip = true
|
||||
|
|
|
|||
137
README.md
137
README.md
|
|
@ -2,41 +2,134 @@
|
|||
|
||||
<h1>PageTop Website</h1>
|
||||
|
||||
<p>Web oficial de <strong>PageTop</strong> para introducir este entorno de desarrollo a la comunidad.</p>
|
||||
<p>Official website of <strong>PageTop</strong>, to introduce this development environment to the community.</p>
|
||||
|
||||
[](#-licencia)
|
||||
[](#license)
|
||||
|
||||
</div>
|
||||
|
||||
## Descripción general
|
||||
## Overview
|
||||
|
||||
Aplicación web creada con `PageTop` para dar a conocer su propio ecosistema a la comunidad,
|
||||
disponible en [pagetop.cillero.es](https://pagetop.cillero.es). Funciona como portal de entrada con
|
||||
documentación completa para desarrolladores y usuarios.
|
||||
Web application built with [PageTop](https://docs.rs/pagetop) to present its own ecosystem to the
|
||||
community, available at [pagetop.cillero.es](https://pagetop.cillero.es). It is the entry point to
|
||||
the PageTop guides for developers and users.
|
||||
|
||||
## Sobre PageTop
|
||||
The guides are [mdBook](https://rust-lang.github.io/mdBook/) books under `doc/`, one per version and
|
||||
language (`doc/<version>/<language>/`), all of them with the theme in `doc/theme/`. They are built
|
||||
and embedded into the binary when the application is compiled, and served as PageTop pages with
|
||||
[pagetop-mdbook](https://git.cillero.es/manuelcillero/pagetop-mdbook).
|
||||
|
||||
[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
|
||||
clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
|
||||
configurables, basadas en HTML, CSS y JavaScript.
|
||||
## Requirements
|
||||
|
||||
- Rust (edition 2024).
|
||||
- [mdBook](https://rust-lang.github.io/mdBook/) 0.4 on the `PATH`, to build the guides (`cargo
|
||||
install mdbook --version "^0.4"`).
|
||||
- The `pagetop` and `pagetop-mdbook` repositories next to this one, as in the `pagetop-projects`
|
||||
workspace: the dependencies use relative paths.
|
||||
|
||||
# 🚧 Advertencia
|
||||
## Running
|
||||
|
||||
`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**.
|
||||
```sh
|
||||
cargo run
|
||||
```
|
||||
|
||||
The server listens on `0.0.0.0:8080` by default. Routes:
|
||||
|
||||
# 📜 Licencia
|
||||
| Route | Content |
|
||||
|-----------------------------|------------------------------------------------------|
|
||||
| `/` | PageTop welcome page |
|
||||
| `/doc/latest/{lang}` | Redirects to the latest guides (Spanish only, by now)|
|
||||
| `/doc/<version>/<lang>/...` | Chapters of the guides |
|
||||
|
||||
El código está disponible bajo una doble licencia:
|
||||
The books are built into `static/doc/` (not versioned) only when their sources change. The version
|
||||
that `/doc/latest/{lang}` points to, and the languages of the guides, are set in `src/lib.rs`
|
||||
(`LATEST_DOC` and `DOC_LANGUAGES`).
|
||||
|
||||
* **Licencia MIT**
|
||||
([LICENSE-MIT](LICENSE-MIT) o también https://opensource.org/licenses/MIT)
|
||||
## Checking the guides
|
||||
|
||||
* **Licencia Apache, Versión 2.0**
|
||||
([LICENSE-APACHE](LICENSE-APACHE) o también https://www.apache.org/licenses/LICENSE-2.0)
|
||||
The guides document the current PageTop code, so they must be checked again whenever PageTop
|
||||
changes. `tools/doccheck.sh` does it in one step:
|
||||
|
||||
Puedes elegir la licencia que prefieras. Este enfoque de doble licencia es el estándar de facto en
|
||||
el ecosistema Rust.
|
||||
```sh
|
||||
tools/doccheck.sh # the latest Spanish guide (doc/v0.6/es)
|
||||
tools/doccheck.sh doc/v0.7/es # any other book
|
||||
```
|
||||
|
||||
It needs `mdbook` and `python3`, and the `pagetop` repository next to this one. It runs three
|
||||
checks and ends with exit code 1 if any fails:
|
||||
|
||||
1. **Links.** Builds the book and checks that every internal link points to an existing page and
|
||||
anchor.
|
||||
2. **Examples.** Extracts every ```` ```rust ```` block into `tools/doccheck/examples/`, removing
|
||||
the `# ` prefix of the lines that mdBook hides, and compiles them against PageTop. Blocks not
|
||||
marked `no_run` are also executed, so their `assert!` are checked.
|
||||
3. **Tests.** Blocks with `#[pagetop::test]` become tests, and run with `cargo test` together with
|
||||
the fixed tests in `tools/doccheck/tests/` (for example, `localization.rs` checks the
|
||||
translations of the localization chapter at run time).
|
||||
|
||||
### How the guides are organized
|
||||
|
||||
Each book follows the four kinds of documentation of [Diátaxis](https://diataxis.fr), one folder
|
||||
each:
|
||||
|
||||
| Folder | Kind | Shape of a page |
|
||||
|---|---|---|
|
||||
| `tutorials/` | Learning by doing, in order | Time, prerequisites and result; numbered steps that run; "what you built"; next steps |
|
||||
| `how-to/` | One task | A **goal** line; numbered steps; the complete example; how to check it; next steps |
|
||||
| `reference/` | Looking things up | Tables: options, components, attributes |
|
||||
| `explanation/` | The why | Prose and diagrams, few examples |
|
||||
|
||||
Every page ends linking the next ones to read. The interactive (HTMX) pages end with a complete,
|
||||
runnable example. `doccheck.sh` compiles it, but what happens in the browser is only declared by its
|
||||
`hx-*` attributes: after changing one of them, run it and try it in a browser.
|
||||
|
||||
When writing a chapter:
|
||||
|
||||
- Write the examples **in English**, whatever the language of the guide: identifiers, strings,
|
||||
comments, paths and configuration values. Translating a guide is then only translating its
|
||||
text. Use another language only where the example needs it (such as the Spanish values of an
|
||||
`es-ES` translation file).
|
||||
- Write every example as **complete, compilable code**. Hide the lines the reader does not need
|
||||
(imports, a wrapping function, helper stubs) with a leading `# `; mdBook does not show them.
|
||||
- Use ```` ```rust ```` only for examples that can run with no server (with `assert!`),
|
||||
```` ```rust,no_run ```` for the rest, and ```` ```rust,ignore ```` only for loose fragments
|
||||
that are not valid on their own.
|
||||
- Examples can use `pagetop`, `pagetop-admin`, `pagetop-bootsier`, `pagetop-cron`,
|
||||
`pagetop-htmx`, `pagetop-mail` (with its `queue` feature), `pagetop-seaorm` (with SQLite),
|
||||
`pagetop-user`, `pagetop-build`, `serde`, `thiserror`, `tokio` and `tower-http` (with the
|
||||
`compression-gzip`, `cors`, `limit` and `timeout` features); the translations in
|
||||
`tools/doccheck/src/locale/` (`LOCALES_APP`), and a static files bundle named `app`. If a chapter needs anything else, add it to `tools/doccheck`.
|
||||
- Examples and tests that start an application read `tools/doccheck/config/`: those with a database
|
||||
get a new in-memory SQLite one on every run, mail is kept in memory (`pagetop_mail::outbox`) and
|
||||
uploaded files go to `tools/doccheck/target/doccheck-uploads`.
|
||||
- Tests that share state (a static store, a database) run in the same process: write one test per
|
||||
flow, so that their results do not depend on the order they run in.
|
||||
|
||||
The first run compiles PageTop and takes a few minutes; the next ones only compile the examples.
|
||||
|
||||
## Configuration
|
||||
|
||||
Settings are loaded in cascade from the `config/` directory (or the one in the `CONFIG_DIR`
|
||||
environment variable): `common.toml`, then `{run_mode}.toml` according to `PAGETOP_RUN_MODE`
|
||||
(`default` by default), `local.{run_mode}.toml` and `local.toml`. The local files are not
|
||||
versioned. Finally, environment variables named `PAGETOP_<SECTION>__<KEY>` override individual
|
||||
keys (e.g. `PAGETOP_SERVER__BIND_PORT=80`).
|
||||
|
||||
## Warning
|
||||
|
||||
**PageTop** is a personal project to learn [Rust](https://www.rust-lang.org/) and its ecosystem. Its
|
||||
API is subject to frequent changes. Production use is not recommended, at least until version
|
||||
**1.0.0** is released.
|
||||
|
||||
## License
|
||||
|
||||
The code is available under a dual license:
|
||||
|
||||
* **MIT License**
|
||||
([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
|
||||
|
||||
* **Apache License, Version 2.0**
|
||||
([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
|
||||
|
||||
You may choose either license. This dual-license approach is the de facto standard in the Rust
|
||||
ecosystem.
|
||||
|
|
|
|||
5
build.rs
Normal file
5
build.rs
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
use pagetop_mdbook::build::{MdBookOptions, mdbooks_and_bundle};
|
||||
|
||||
fn main() -> std::io::Result<()> {
|
||||
mdbooks_and_bundle(MdBookOptions::new())
|
||||
}
|
||||
30
config/common.toml
Normal file
30
config/common.toml
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Settings common to all environments.
|
||||
#
|
||||
# Load order (all optional):
|
||||
# 1. config/common.toml <- this file
|
||||
# 2. config/{run_mode}.toml <- according to PAGETOP_RUN_MODE (default: "default")
|
||||
# 3. config/local.{run_mode}.toml
|
||||
# 4. config/local.toml <- local overrides, do not track in git
|
||||
#
|
||||
# Finally, environment variables named PAGETOP_<SECTION>__<KEY> override any key of these files,
|
||||
# with each level separated by a double underscore (e.g. PAGETOP_SERVER__BIND_PORT=80). Besides,
|
||||
# PAGETOP_RUN_MODE (see above) and CONFIG_DIR (an alternative to the "config" directory) choose
|
||||
# which files are loaded.
|
||||
|
||||
# **< Application >*********************************************************************************
|
||||
|
||||
[app]
|
||||
name = "PageTop"
|
||||
theme = "Bootsier"
|
||||
# Interface language: "es" (default) or "en".
|
||||
language = "es"
|
||||
|
||||
# **< Theme >***************************************************************************************
|
||||
|
||||
[bootsier]
|
||||
max_width = "1520px"
|
||||
|
||||
# **< Trace logging >*******************************************************************************
|
||||
|
||||
[log]
|
||||
rolling = "Daily"
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
[app]
|
||||
name = "PageTop"
|
||||
description = "An opinionated web framework to build modular Server-Side Rendering web solutions."
|
||||
|
||||
[log]
|
||||
rolling = "Daily"
|
||||
655
doc/theme/book.js
vendored
Normal file
655
doc/theme/book.js
vendored
Normal file
|
|
@ -0,0 +1,655 @@
|
|||
"use strict";
|
||||
|
||||
// Fix back button cache problem
|
||||
window.onunload = function () { };
|
||||
|
||||
// Global variable, shared between modules
|
||||
function playground_text(playground, hidden = true) {
|
||||
let code_block = playground.querySelector("code");
|
||||
|
||||
if (window.ace && code_block.classList.contains("editable")) {
|
||||
let editor = window.ace.edit(code_block);
|
||||
return editor.getValue();
|
||||
} else if (hidden) {
|
||||
return code_block.textContent;
|
||||
} else {
|
||||
return code_block.innerText;
|
||||
}
|
||||
}
|
||||
|
||||
(function codeSnippets() {
|
||||
function fetch_with_timeout(url, options, timeout = 6000) {
|
||||
return Promise.race([
|
||||
fetch(url, options),
|
||||
new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout))
|
||||
]);
|
||||
}
|
||||
|
||||
var playgrounds = Array.from(document.querySelectorAll(".playground"));
|
||||
if (playgrounds.length > 0) {
|
||||
fetch_with_timeout("https://play.rust-lang.org/meta/crates", {
|
||||
headers: {
|
||||
'Content-Type': "application/json",
|
||||
},
|
||||
method: 'POST',
|
||||
mode: 'cors',
|
||||
})
|
||||
.then(response => response.json())
|
||||
.then(response => {
|
||||
// get list of crates available in the rust playground
|
||||
let playground_crates = response.crates.map(item => item["id"]);
|
||||
playgrounds.forEach(block => handle_crate_list_update(block, playground_crates));
|
||||
});
|
||||
}
|
||||
|
||||
function handle_crate_list_update(playground_block, playground_crates) {
|
||||
// update the play buttons after receiving the response
|
||||
update_play_button(playground_block, playground_crates);
|
||||
|
||||
// and install on change listener to dynamically update ACE editors
|
||||
if (window.ace) {
|
||||
let code_block = playground_block.querySelector("code");
|
||||
if (code_block.classList.contains("editable")) {
|
||||
let editor = window.ace.edit(code_block);
|
||||
editor.addEventListener("change", function (e) {
|
||||
update_play_button(playground_block, playground_crates);
|
||||
});
|
||||
// add Ctrl-Enter command to execute rust code
|
||||
editor.commands.addCommand({
|
||||
name: "run",
|
||||
bindKey: {
|
||||
win: "Ctrl-Enter",
|
||||
mac: "Ctrl-Enter"
|
||||
},
|
||||
exec: _editor => run_rust_code(playground_block)
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// updates the visibility of play button based on `no_run` class and
|
||||
// used crates vs ones available on https://play.rust-lang.org
|
||||
function update_play_button(pre_block, playground_crates) {
|
||||
var play_button = pre_block.querySelector(".play-button");
|
||||
|
||||
// skip if code is `no_run`
|
||||
if (pre_block.querySelector('code').classList.contains("no_run")) {
|
||||
play_button.classList.add("hidden");
|
||||
return;
|
||||
}
|
||||
|
||||
// get list of `extern crate`'s from snippet
|
||||
var txt = playground_text(pre_block);
|
||||
var re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
|
||||
var snippet_crates = [];
|
||||
var item;
|
||||
while (item = re.exec(txt)) {
|
||||
snippet_crates.push(item[1]);
|
||||
}
|
||||
|
||||
// check if all used crates are available on play.rust-lang.org
|
||||
var all_available = snippet_crates.every(function (elem) {
|
||||
return playground_crates.indexOf(elem) > -1;
|
||||
});
|
||||
|
||||
if (all_available) {
|
||||
play_button.classList.remove("hidden");
|
||||
} else {
|
||||
play_button.classList.add("hidden");
|
||||
}
|
||||
}
|
||||
|
||||
function run_rust_code(code_block) {
|
||||
var result_block = code_block.querySelector(".result");
|
||||
if (!result_block) {
|
||||
result_block = document.createElement('code');
|
||||
result_block.className = 'result hljs language-bash';
|
||||
|
||||
code_block.append(result_block);
|
||||
}
|
||||
|
||||
let text = playground_text(code_block);
|
||||
let classes = code_block.querySelector('code').classList;
|
||||
let edition = "2015";
|
||||
if(classes.contains("edition2018")) {
|
||||
edition = "2018";
|
||||
} else if(classes.contains("edition2021")) {
|
||||
edition = "2021";
|
||||
}
|
||||
var params = {
|
||||
version: "stable",
|
||||
optimize: "0",
|
||||
code: text,
|
||||
edition: edition
|
||||
};
|
||||
|
||||
if (text.indexOf("#![feature") !== -1) {
|
||||
params.version = "nightly";
|
||||
}
|
||||
|
||||
result_block.innerText = "Running...";
|
||||
|
||||
fetch_with_timeout("https://play.rust-lang.org/evaluate.json", {
|
||||
headers: {
|
||||
'Content-Type': "application/json",
|
||||
},
|
||||
method: 'POST',
|
||||
mode: 'cors',
|
||||
body: JSON.stringify(params)
|
||||
})
|
||||
.then(response => response.json())
|
||||
.then(response => {
|
||||
if (response.result.trim() === '') {
|
||||
result_block.innerText = "No output";
|
||||
result_block.classList.add("result-no-output");
|
||||
} else {
|
||||
result_block.innerText = response.result;
|
||||
result_block.classList.remove("result-no-output");
|
||||
}
|
||||
})
|
||||
.catch(error => result_block.innerText = "Playground Communication: " + error.message);
|
||||
}
|
||||
|
||||
// Syntax highlighting Configuration
|
||||
hljs.configure({
|
||||
tabReplace: ' ', // 4 spaces
|
||||
languages: [], // Languages used for auto-detection
|
||||
});
|
||||
|
||||
let code_nodes = Array
|
||||
.from(document.querySelectorAll('code'))
|
||||
// Don't highlight `inline code` blocks in headers.
|
||||
.filter(function (node) {return !node.parentElement.classList.contains("header"); });
|
||||
|
||||
if (window.ace) {
|
||||
// language-rust class needs to be removed for editable
|
||||
// blocks or highlightjs will capture events
|
||||
code_nodes
|
||||
.filter(function (node) {return node.classList.contains("editable"); })
|
||||
.forEach(function (block) { block.classList.remove('language-rust'); });
|
||||
|
||||
code_nodes
|
||||
.filter(function (node) {return !node.classList.contains("editable"); })
|
||||
.forEach(function (block) { hljs.highlightBlock(block); });
|
||||
} else {
|
||||
code_nodes.forEach(function (block) { hljs.highlightBlock(block); });
|
||||
}
|
||||
|
||||
// Adding the hljs class gives code blocks the color css
|
||||
// even if highlighting doesn't apply
|
||||
code_nodes.forEach(function (block) { block.classList.add('hljs'); });
|
||||
|
||||
Array.from(document.querySelectorAll("code.hljs")).forEach(function (block) {
|
||||
|
||||
var lines = Array.from(block.querySelectorAll('.boring'));
|
||||
// If no lines were hidden, return
|
||||
if (!lines.length) { return; }
|
||||
block.classList.add("hide-boring");
|
||||
|
||||
var buttons = document.createElement('div');
|
||||
buttons.className = 'buttons';
|
||||
buttons.innerHTML = "<button class=\"fa fa-eye\" title=\"Show hidden lines\" aria-label=\"Show hidden lines\"></button>";
|
||||
|
||||
// add expand button
|
||||
var pre_block = block.parentNode;
|
||||
pre_block.insertBefore(buttons, pre_block.firstChild);
|
||||
|
||||
pre_block.querySelector('.buttons').addEventListener('click', function (e) {
|
||||
if (e.target.classList.contains('fa-eye')) {
|
||||
e.target.classList.remove('fa-eye');
|
||||
e.target.classList.add('fa-eye-slash');
|
||||
e.target.title = 'Hide lines';
|
||||
e.target.setAttribute('aria-label', e.target.title);
|
||||
|
||||
block.classList.remove('hide-boring');
|
||||
} else if (e.target.classList.contains('fa-eye-slash')) {
|
||||
e.target.classList.remove('fa-eye-slash');
|
||||
e.target.classList.add('fa-eye');
|
||||
e.target.title = 'Show hidden lines';
|
||||
e.target.setAttribute('aria-label', e.target.title);
|
||||
|
||||
block.classList.add('hide-boring');
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
if (window.playground_copyable) {
|
||||
Array.from(document.querySelectorAll('pre code')).forEach(function (block) {
|
||||
var pre_block = block.parentNode;
|
||||
if (!pre_block.classList.contains('playground')) {
|
||||
var buttons = pre_block.querySelector(".buttons");
|
||||
if (!buttons) {
|
||||
buttons = document.createElement('div');
|
||||
buttons.className = 'buttons';
|
||||
pre_block.insertBefore(buttons, pre_block.firstChild);
|
||||
}
|
||||
|
||||
var clipButton = document.createElement('button');
|
||||
clipButton.className = 'fa fa-copy clip-button';
|
||||
clipButton.title = 'Copy to clipboard';
|
||||
clipButton.setAttribute('aria-label', clipButton.title);
|
||||
clipButton.innerHTML = '<i class=\"tooltiptext\"></i>';
|
||||
|
||||
buttons.insertBefore(clipButton, buttons.firstChild);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// Process playground code blocks
|
||||
Array.from(document.querySelectorAll(".playground")).forEach(function (pre_block) {
|
||||
// Add play button
|
||||
var buttons = pre_block.querySelector(".buttons");
|
||||
if (!buttons) {
|
||||
buttons = document.createElement('div');
|
||||
buttons.className = 'buttons';
|
||||
pre_block.insertBefore(buttons, pre_block.firstChild);
|
||||
}
|
||||
|
||||
var runCodeButton = document.createElement('button');
|
||||
runCodeButton.className = 'fa fa-play play-button';
|
||||
runCodeButton.hidden = true;
|
||||
runCodeButton.title = 'Run this code';
|
||||
runCodeButton.setAttribute('aria-label', runCodeButton.title);
|
||||
|
||||
buttons.insertBefore(runCodeButton, buttons.firstChild);
|
||||
runCodeButton.addEventListener('click', function (e) {
|
||||
run_rust_code(pre_block);
|
||||
});
|
||||
|
||||
if (window.playground_copyable) {
|
||||
var copyCodeClipboardButton = document.createElement('button');
|
||||
copyCodeClipboardButton.className = 'fa fa-copy clip-button';
|
||||
copyCodeClipboardButton.innerHTML = '<i class="tooltiptext"></i>';
|
||||
copyCodeClipboardButton.title = 'Copy to clipboard';
|
||||
copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title);
|
||||
|
||||
buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild);
|
||||
}
|
||||
|
||||
let code_block = pre_block.querySelector("code");
|
||||
if (window.ace && code_block.classList.contains("editable")) {
|
||||
var undoChangesButton = document.createElement('button');
|
||||
undoChangesButton.className = 'fa fa-history reset-button';
|
||||
undoChangesButton.title = 'Undo changes';
|
||||
undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
|
||||
|
||||
buttons.insertBefore(undoChangesButton, buttons.firstChild);
|
||||
|
||||
undoChangesButton.addEventListener('click', function () {
|
||||
let editor = window.ace.edit(code_block);
|
||||
editor.setValue(editor.originalCode);
|
||||
editor.clearSelection();
|
||||
});
|
||||
}
|
||||
});
|
||||
})();
|
||||
|
||||
(function themes() {
|
||||
var html = document.querySelector('html');
|
||||
var themeToggleButton = document.getElementById('theme-toggle');
|
||||
var themePopup = document.getElementById('theme-list');
|
||||
var themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
|
||||
var stylesheets = {
|
||||
ayuHighlight: document.querySelector("[href$='ayu-highlight.css']"),
|
||||
tomorrowNight: document.querySelector("[href$='tomorrow-night.css']"),
|
||||
highlight: document.querySelector("[href$='highlight.css']"),
|
||||
};
|
||||
|
||||
function showThemes() {
|
||||
themePopup.style.display = 'block';
|
||||
themeToggleButton.setAttribute('aria-expanded', true);
|
||||
themePopup.querySelector("button#" + get_theme()).focus();
|
||||
}
|
||||
|
||||
function updateThemeSelected() {
|
||||
themePopup.querySelectorAll('.theme-selected').forEach(function (el) {
|
||||
el.classList.remove('theme-selected');
|
||||
});
|
||||
themePopup.querySelector("button#" + get_theme()).classList.add('theme-selected');
|
||||
}
|
||||
|
||||
function hideThemes() {
|
||||
themePopup.style.display = 'none';
|
||||
themeToggleButton.setAttribute('aria-expanded', false);
|
||||
themeToggleButton.focus();
|
||||
}
|
||||
|
||||
function get_theme() {
|
||||
var theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch (e) { }
|
||||
if (theme === null || theme === undefined) {
|
||||
return default_theme;
|
||||
} else {
|
||||
return theme;
|
||||
}
|
||||
}
|
||||
|
||||
function set_theme(theme, store = true) {
|
||||
let ace_theme;
|
||||
|
||||
if (theme == 'coal' || theme == 'navy') {
|
||||
stylesheets.ayuHighlight.disabled = true;
|
||||
stylesheets.tomorrowNight.disabled = false;
|
||||
stylesheets.highlight.disabled = true;
|
||||
|
||||
ace_theme = "ace/theme/tomorrow_night";
|
||||
} else if (theme == 'ayu') {
|
||||
stylesheets.ayuHighlight.disabled = false;
|
||||
stylesheets.tomorrowNight.disabled = true;
|
||||
stylesheets.highlight.disabled = true;
|
||||
ace_theme = "ace/theme/tomorrow_night";
|
||||
} else {
|
||||
stylesheets.ayuHighlight.disabled = true;
|
||||
stylesheets.tomorrowNight.disabled = true;
|
||||
stylesheets.highlight.disabled = false;
|
||||
ace_theme = "ace/theme/dawn";
|
||||
}
|
||||
|
||||
setTimeout(function () {
|
||||
themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor;
|
||||
}, 1);
|
||||
|
||||
if (window.ace && window.editors) {
|
||||
window.editors.forEach(function (editor) {
|
||||
editor.setTheme(ace_theme);
|
||||
});
|
||||
}
|
||||
|
||||
var previousTheme = get_theme();
|
||||
|
||||
if (store) {
|
||||
try { localStorage.setItem('mdbook-theme', theme); } catch (e) { }
|
||||
}
|
||||
|
||||
html.classList.remove(previousTheme);
|
||||
html.classList.add(theme);
|
||||
updateThemeSelected();
|
||||
}
|
||||
|
||||
// Set theme
|
||||
var theme = get_theme();
|
||||
|
||||
set_theme(theme, false);
|
||||
|
||||
themeToggleButton.addEventListener('click', function () {
|
||||
if (themePopup.style.display === 'block') {
|
||||
hideThemes();
|
||||
} else {
|
||||
showThemes();
|
||||
}
|
||||
});
|
||||
|
||||
themePopup.addEventListener('click', function (e) {
|
||||
var theme;
|
||||
if (e.target.className === "theme") {
|
||||
theme = e.target.id;
|
||||
} else if (e.target.parentElement.className === "theme") {
|
||||
theme = e.target.parentElement.id;
|
||||
} else {
|
||||
return;
|
||||
}
|
||||
set_theme(theme);
|
||||
});
|
||||
|
||||
themePopup.addEventListener('focusout', function(e) {
|
||||
// e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
|
||||
if (!!e.relatedTarget && !themeToggleButton.contains(e.relatedTarget) && !themePopup.contains(e.relatedTarget)) {
|
||||
hideThemes();
|
||||
}
|
||||
});
|
||||
|
||||
// Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang/mdBook/issues/628
|
||||
document.addEventListener('click', function(e) {
|
||||
if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) {
|
||||
hideThemes();
|
||||
}
|
||||
});
|
||||
|
||||
document.addEventListener('keydown', function (e) {
|
||||
if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
|
||||
if (!themePopup.contains(e.target)) { return; }
|
||||
|
||||
switch (e.key) {
|
||||
case 'Escape':
|
||||
e.preventDefault();
|
||||
hideThemes();
|
||||
break;
|
||||
case 'ArrowUp':
|
||||
e.preventDefault();
|
||||
var li = document.activeElement.parentElement;
|
||||
if (li && li.previousElementSibling) {
|
||||
li.previousElementSibling.querySelector('button').focus();
|
||||
}
|
||||
break;
|
||||
case 'ArrowDown':
|
||||
e.preventDefault();
|
||||
var li = document.activeElement.parentElement;
|
||||
if (li && li.nextElementSibling) {
|
||||
li.nextElementSibling.querySelector('button').focus();
|
||||
}
|
||||
break;
|
||||
case 'Home':
|
||||
e.preventDefault();
|
||||
themePopup.querySelector('li:first-child button').focus();
|
||||
break;
|
||||
case 'End':
|
||||
e.preventDefault();
|
||||
themePopup.querySelector('li:last-child button').focus();
|
||||
break;
|
||||
}
|
||||
});
|
||||
})();
|
||||
|
||||
(function sidebar() {
|
||||
var body = document.querySelector("body");
|
||||
var sidebar = document.getElementById("sidebar");
|
||||
var sidebarLinks = document.querySelectorAll('#sidebar a');
|
||||
var sidebarToggleButton = document.getElementById("sidebar-toggle");
|
||||
var sidebarResizeHandle = document.getElementById("sidebar-resize-handle");
|
||||
var firstContact = null;
|
||||
|
||||
function showSidebar() {
|
||||
body.classList.remove('sidebar-hidden')
|
||||
body.classList.add('sidebar-visible');
|
||||
Array.from(sidebarLinks).forEach(function (link) {
|
||||
link.setAttribute('tabIndex', 0);
|
||||
});
|
||||
sidebarToggleButton.setAttribute('aria-expanded', true);
|
||||
sidebar.setAttribute('aria-hidden', false);
|
||||
try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
|
||||
}
|
||||
|
||||
|
||||
var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle');
|
||||
|
||||
function toggleSection(ev) {
|
||||
ev.currentTarget.parentElement.classList.toggle('expanded');
|
||||
}
|
||||
|
||||
Array.from(sidebarAnchorToggles).forEach(function (el) {
|
||||
el.addEventListener('click', toggleSection);
|
||||
});
|
||||
|
||||
function hideSidebar() {
|
||||
body.classList.remove('sidebar-visible')
|
||||
body.classList.add('sidebar-hidden');
|
||||
Array.from(sidebarLinks).forEach(function (link) {
|
||||
link.setAttribute('tabIndex', -1);
|
||||
});
|
||||
sidebarToggleButton.setAttribute('aria-expanded', false);
|
||||
sidebar.setAttribute('aria-hidden', true);
|
||||
try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
|
||||
}
|
||||
|
||||
// Toggle sidebar
|
||||
sidebarToggleButton.addEventListener('click', function sidebarToggle() {
|
||||
if (body.classList.contains("sidebar-hidden")) {
|
||||
var current_width = parseInt(
|
||||
document.documentElement.style.getPropertyValue('--sidebar-width'), 10);
|
||||
if (current_width < 150) {
|
||||
document.documentElement.style.setProperty('--sidebar-width', '150px');
|
||||
}
|
||||
showSidebar();
|
||||
} else if (body.classList.contains("sidebar-visible")) {
|
||||
hideSidebar();
|
||||
} else {
|
||||
if (getComputedStyle(sidebar)['transform'] === 'none') {
|
||||
hideSidebar();
|
||||
} else {
|
||||
showSidebar();
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
sidebarResizeHandle.addEventListener('mousedown', initResize, false);
|
||||
|
||||
function initResize(e) {
|
||||
window.addEventListener('mousemove', resize, false);
|
||||
window.addEventListener('mouseup', stopResize, false);
|
||||
body.classList.add('sidebar-resizing');
|
||||
}
|
||||
function resize(e) {
|
||||
var viewportOffset = sidebar.getBoundingClientRect();
|
||||
var pos = (e.clientX - sidebar.offsetLeft - viewportOffset.left);
|
||||
if (pos < 20) {
|
||||
hideSidebar();
|
||||
} else {
|
||||
if (body.classList.contains("sidebar-hidden")) {
|
||||
showSidebar();
|
||||
}
|
||||
pos = Math.min(pos, window.innerWidth - 100);
|
||||
document.documentElement.style.setProperty('--sidebar-width', pos + 'px');
|
||||
}
|
||||
}
|
||||
//on mouseup remove windows functions mousemove & mouseup
|
||||
function stopResize(e) {
|
||||
body.classList.remove('sidebar-resizing');
|
||||
window.removeEventListener('mousemove', resize, false);
|
||||
window.removeEventListener('mouseup', stopResize, false);
|
||||
}
|
||||
|
||||
document.addEventListener('touchstart', function (e) {
|
||||
firstContact = {
|
||||
x: e.touches[0].clientX,
|
||||
time: Date.now()
|
||||
};
|
||||
}, { passive: true });
|
||||
|
||||
document.addEventListener('touchmove', function (e) {
|
||||
if (!firstContact)
|
||||
return;
|
||||
|
||||
var curX = e.touches[0].clientX;
|
||||
var xDiff = curX - firstContact.x,
|
||||
tDiff = Date.now() - firstContact.time;
|
||||
|
||||
if (tDiff < 250 && Math.abs(xDiff) >= 150) {
|
||||
if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
|
||||
showSidebar();
|
||||
else if (xDiff < 0 && curX < 300)
|
||||
hideSidebar();
|
||||
|
||||
firstContact = null;
|
||||
}
|
||||
}, { passive: true });
|
||||
})();
|
||||
|
||||
(function chapterNavigation() {
|
||||
document.addEventListener('keydown', function (e) {
|
||||
if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
|
||||
if (window.search && window.search.hasFocus()) { return; }
|
||||
var html = document.querySelector('html');
|
||||
|
||||
function next() {
|
||||
var nextButton = document.querySelector('.nav-chapters.next');
|
||||
if (nextButton) {
|
||||
window.location.href = nextButton.href;
|
||||
}
|
||||
}
|
||||
function prev() {
|
||||
var previousButton = document.querySelector('.nav-chapters.previous');
|
||||
if (previousButton) {
|
||||
window.location.href = previousButton.href;
|
||||
}
|
||||
}
|
||||
switch (e.key) {
|
||||
case 'ArrowRight':
|
||||
e.preventDefault();
|
||||
if (html.dir == 'rtl') {
|
||||
prev();
|
||||
} else {
|
||||
next();
|
||||
}
|
||||
break;
|
||||
case 'ArrowLeft':
|
||||
e.preventDefault();
|
||||
if (html.dir == 'rtl') {
|
||||
next();
|
||||
} else {
|
||||
prev();
|
||||
}
|
||||
break;
|
||||
}
|
||||
});
|
||||
})();
|
||||
|
||||
(function clipboard() {
|
||||
var clipButtons = document.querySelectorAll('.clip-button');
|
||||
|
||||
function hideTooltip(elem) {
|
||||
elem.firstChild.innerText = "";
|
||||
elem.className = 'fa fa-copy clip-button';
|
||||
}
|
||||
|
||||
function showTooltip(elem, msg) {
|
||||
elem.firstChild.innerText = msg;
|
||||
elem.className = 'fa fa-copy tooltipped';
|
||||
}
|
||||
|
||||
var clipboardSnippets = new ClipboardJS('.clip-button', {
|
||||
text: function (trigger) {
|
||||
hideTooltip(trigger);
|
||||
let playground = trigger.closest("pre");
|
||||
return playground_text(playground, false);
|
||||
}
|
||||
});
|
||||
|
||||
Array.from(clipButtons).forEach(function (clipButton) {
|
||||
clipButton.addEventListener('mouseout', function (e) {
|
||||
hideTooltip(e.currentTarget);
|
||||
});
|
||||
});
|
||||
|
||||
clipboardSnippets.on('success', function (e) {
|
||||
e.clearSelection();
|
||||
showTooltip(e.trigger, "Copied!");
|
||||
});
|
||||
|
||||
clipboardSnippets.on('error', function (e) {
|
||||
showTooltip(e.trigger, "Clipboard error!");
|
||||
});
|
||||
})();
|
||||
|
||||
(function scrollToTop () {
|
||||
var menuTitle = document.querySelector('.menu-title');
|
||||
|
||||
menuTitle.addEventListener('click', function () {
|
||||
document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
|
||||
});
|
||||
})();
|
||||
|
||||
(function controllMenu() {
|
||||
var menu = document.getElementById('menu-bar');
|
||||
|
||||
(function controllBorder() {
|
||||
function updateBorder() {
|
||||
if (menu.offsetTop === 0) {
|
||||
menu.classList.remove('bordered');
|
||||
} else {
|
||||
menu.classList.add('bordered');
|
||||
}
|
||||
}
|
||||
updateBorder();
|
||||
document.addEventListener('scroll', updateBorder, { passive: true });
|
||||
})();
|
||||
})();
|
||||
82
doc/theme/highlight.css
vendored
Normal file
82
doc/theme/highlight.css
vendored
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
/*
|
||||
* An increased contrast highlighting scheme loosely based on the
|
||||
* "Base16 Atelier Dune Light" theme by Bram de Haan
|
||||
* (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune)
|
||||
* Original Base16 color scheme by Chris Kempson
|
||||
* (https://github.com/chriskempson/base16)
|
||||
*/
|
||||
|
||||
/* Comment */
|
||||
.hljs-comment,
|
||||
.hljs-quote {
|
||||
color: #575757;
|
||||
}
|
||||
|
||||
/* Red */
|
||||
.hljs-variable,
|
||||
.hljs-template-variable,
|
||||
.hljs-attribute,
|
||||
.hljs-tag,
|
||||
.hljs-name,
|
||||
.hljs-regexp,
|
||||
.hljs-link,
|
||||
.hljs-name,
|
||||
.hljs-selector-id,
|
||||
.hljs-selector-class {
|
||||
color: #d70025;
|
||||
}
|
||||
|
||||
/* Orange */
|
||||
.hljs-number,
|
||||
.hljs-meta,
|
||||
.hljs-built_in,
|
||||
.hljs-builtin-name,
|
||||
.hljs-literal,
|
||||
.hljs-type,
|
||||
.hljs-params {
|
||||
color: #b21e00;
|
||||
}
|
||||
|
||||
/* Green */
|
||||
.hljs-string,
|
||||
.hljs-symbol,
|
||||
.hljs-bullet {
|
||||
color: #008200;
|
||||
}
|
||||
|
||||
/* Blue */
|
||||
.hljs-title,
|
||||
.hljs-section {
|
||||
color: #0030f2;
|
||||
}
|
||||
|
||||
/* Purple */
|
||||
.hljs-keyword,
|
||||
.hljs-selector-tag {
|
||||
color: #9d00ec;
|
||||
}
|
||||
|
||||
.hljs {
|
||||
display: block;
|
||||
overflow-x: auto;
|
||||
background: #f6f7f6;
|
||||
color: #000;
|
||||
}
|
||||
|
||||
.hljs-emphasis {
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
.hljs-strong {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.hljs-addition {
|
||||
color: #22863a;
|
||||
background-color: #f0fff4;
|
||||
}
|
||||
|
||||
.hljs-deletion {
|
||||
color: #b31d28;
|
||||
background-color: #ffeef0;
|
||||
}
|
||||
53
doc/theme/highlight.js
vendored
Normal file
53
doc/theme/highlight.js
vendored
Normal file
File diff suppressed because one or more lines are too long
292
doc/theme/index.hbs
vendored
Normal file
292
doc/theme/index.hbs
vendored
Normal file
|
|
@ -0,0 +1,292 @@
|
|||
<!-- Lang: {{ language }} -->
|
||||
<!-- Title: {{ title }} -->
|
||||
<!-- Print: {{#if print_enable}}enabled{{else}}disabled{{/if}} -->
|
||||
<!-- MathJax: {{#if mathjax_support}}supported{{else}}unsupported{{/if}} -->
|
||||
|
||||
<!-- mdBook -->
|
||||
|
||||
<!-- Provide site root to javascript -->
|
||||
<script>
|
||||
var path_to_root = "{{ path_to_root }}";
|
||||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "{{ preferred_dark_theme }}" : "{{ default_theme }}";
|
||||
</script>
|
||||
|
||||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||||
<script>
|
||||
try {
|
||||
var theme = localStorage.getItem('mdbook-theme');
|
||||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||||
|
||||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||||
}
|
||||
|
||||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||||
}
|
||||
} catch (e) { }
|
||||
</script>
|
||||
|
||||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||||
<script>
|
||||
var theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||||
var html = document.querySelector('html');
|
||||
html.classList.remove('{{ default_theme }}')
|
||||
html.classList.add(theme);
|
||||
var body = document.querySelector('body');
|
||||
body.classList.remove('no-js')
|
||||
body.classList.add('js');
|
||||
</script>
|
||||
|
||||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||||
|
||||
<!-- Hide / unhide sidebar before it is displayed -->
|
||||
<script>
|
||||
var body = document.querySelector('body');
|
||||
var sidebar = null;
|
||||
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||||
if (document.body.clientWidth >= 1080) {
|
||||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||||
sidebar = sidebar || 'visible';
|
||||
} else {
|
||||
sidebar = 'hidden';
|
||||
}
|
||||
sidebar_toggle.checked = sidebar === 'visible';
|
||||
body.classList.remove('sidebar-visible');
|
||||
body.classList.add("sidebar-" + sidebar);
|
||||
</script>
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<div class="sidebar-scrollbox">
|
||||
{{#toc}}{{/toc}}
|
||||
</div>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||||
<div class="sidebar-resize-indicator"></div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<!-- Track and set sidebar scroll position -->
|
||||
<script>
|
||||
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
|
||||
sidebarScrollbox.addEventListener('click', function(e) {
|
||||
if (e.target.tagName === 'A') {
|
||||
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
|
||||
}
|
||||
}, { passive: true });
|
||||
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
|
||||
sessionStorage.removeItem('sidebar-scroll');
|
||||
if (sidebarScrollTop) {
|
||||
// preserve sidebar scroll position when navigating via links within sidebar
|
||||
sidebarScrollbox.scrollTop = sidebarScrollTop;
|
||||
} else {
|
||||
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
|
||||
var activeSection = document.querySelector('#sidebar .active');
|
||||
if (activeSection) {
|
||||
activeSection.scrollIntoView({ block: 'center' });
|
||||
}
|
||||
}
|
||||
</script>
|
||||
|
||||
<div id="page-wrapper" class="page-wrapper">
|
||||
|
||||
<div class="page">
|
||||
{{> header}}
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky">
|
||||
<div class="left-buttons">
|
||||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||||
<i class="fa fa-bars"></i>
|
||||
</label>
|
||||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||||
<i class="fa fa-paint-brush"></i>
|
||||
</button>
|
||||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||||
</ul>
|
||||
{{#if search_enabled}}
|
||||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||||
<i class="fa fa-search"></i>
|
||||
</button>
|
||||
{{/if}}
|
||||
</div>
|
||||
|
||||
<h1 class="menu-title">{{ book_title }}</h1>
|
||||
|
||||
<div class="right-buttons">
|
||||
{{#if print_enable}}
|
||||
<a href="{{ path_to_root }}print.html" title="Print this book" aria-label="Print this book">
|
||||
<i id="print-button" class="fa fa-print"></i>
|
||||
</a>
|
||||
{{/if}}
|
||||
{{#if git_repository_url}}
|
||||
<a href="{{git_repository_url}}" title="Git repository" aria-label="Git repository">
|
||||
<i id="git-repository-button" class="fa {{git_repository_icon}}"></i>
|
||||
</a>
|
||||
{{/if}}
|
||||
{{#if git_repository_edit_url}}
|
||||
<a href="{{git_repository_edit_url}}" title="Suggest an edit" aria-label="Suggest an edit">
|
||||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||||
</a>
|
||||
{{/if}}
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{{#if search_enabled}}
|
||||
<div id="search-wrapper" class="hidden">
|
||||
<form id="searchbar-outer" class="searchbar-outer">
|
||||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
</form>
|
||||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||||
<div id="searchresults-header" class="searchresults-header"></div>
|
||||
<ul id="searchresults">
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
{{/if}}
|
||||
|
||||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||||
<script>
|
||||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||||
});
|
||||
</script>
|
||||
|
||||
<div id="content" class="content">
|
||||
<main>
|
||||
{{{ content }}}
|
||||
</main>
|
||||
|
||||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||||
<!-- Mobile navigation buttons -->
|
||||
{{#previous}}
|
||||
<a rel="prev" href="{{ path_to_root }}{{link}}" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
{{/previous}}
|
||||
|
||||
{{#next}}
|
||||
<a rel="next prefetch" href="{{ path_to_root }}{{link}}" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
{{/next}}
|
||||
|
||||
<div style="clear: both"></div>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||||
{{#previous}}
|
||||
<a rel="prev" href="{{ path_to_root }}{{link}}" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
{{/previous}}
|
||||
|
||||
{{#next}}
|
||||
<a rel="next prefetch" href="{{ path_to_root }}{{link}}" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
{{/next}}
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
{{#if live_reload_endpoint}}
|
||||
<!-- Livereload script (if served using the cli tool) -->
|
||||
<script>
|
||||
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
||||
const wsAddress = wsProtocol + "//" + location.host + "/" + "{{{live_reload_endpoint}}}";
|
||||
const socket = new WebSocket(wsAddress);
|
||||
socket.onmessage = function (event) {
|
||||
if (event.data === "reload") {
|
||||
socket.close();
|
||||
location.reload();
|
||||
}
|
||||
};
|
||||
|
||||
window.onbeforeunload = function() {
|
||||
socket.close();
|
||||
}
|
||||
</script>
|
||||
{{/if}}
|
||||
|
||||
{{#if google_analytics}}
|
||||
<!-- Google Analytics Tag -->
|
||||
<script>
|
||||
var localAddrs = ["localhost", "127.0.0.1", ""];
|
||||
|
||||
// make sure we don't activate google analytics if the developer is
|
||||
// inspecting the book locally...
|
||||
if (localAddrs.indexOf(document.location.hostname) === -1) {
|
||||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
||||
|
||||
ga('create', '{{google_analytics}}', 'auto');
|
||||
ga('send', 'pageview');
|
||||
}
|
||||
</script>
|
||||
{{/if}}
|
||||
|
||||
{{#if playground_line_numbers}}
|
||||
<script>
|
||||
window.playground_line_numbers = true;
|
||||
</script>
|
||||
{{/if}}
|
||||
|
||||
{{#if playground_copyable}}
|
||||
<script>
|
||||
window.playground_copyable = true;
|
||||
</script>
|
||||
{{/if}}
|
||||
|
||||
{{#if playground_js}}
|
||||
<script src="{{ path_to_root }}ace.js"></script>
|
||||
<script src="{{ path_to_root }}editor.js"></script>
|
||||
<script src="{{ path_to_root }}mode-rust.js"></script>
|
||||
<script src="{{ path_to_root }}theme-dawn.js"></script>
|
||||
<script src="{{ path_to_root }}theme-tomorrow_night.js"></script>
|
||||
{{/if}}
|
||||
|
||||
{{#if search_js}}
|
||||
<script src="{{ path_to_root }}elasticlunr.min.js"></script>
|
||||
<script src="{{ path_to_root }}mark.min.js"></script>
|
||||
<script src="{{ path_to_root }}searcher.js"></script>
|
||||
{{/if}}
|
||||
|
||||
<script src="{{ path_to_root }}clipboard.min.js"></script>
|
||||
<script src="{{ path_to_root }}highlight.js"></script>
|
||||
<script src="{{ path_to_root }}book.js"></script>
|
||||
|
||||
<!-- Custom JS scripts -->
|
||||
{{#each additional_js}}
|
||||
<script src="{{ ../path_to_root }}{{this}}"></script>
|
||||
{{/each}}
|
||||
|
||||
{{#if is_print}}
|
||||
{{#if mathjax_support}}
|
||||
<script>
|
||||
window.addEventListener('load', function() {
|
||||
MathJax.Hub.Register.StartupHook('End', function() {
|
||||
window.setTimeout(window.print, 100);
|
||||
});
|
||||
});
|
||||
</script>
|
||||
{{else}}
|
||||
<script>
|
||||
window.addEventListener('load', function() {
|
||||
window.setTimeout(window.print, 100);
|
||||
});
|
||||
</script>
|
||||
{{/if}}
|
||||
{{/if}}
|
||||
14
doc/v0.6/es/book.toml
Normal file
14
doc/v0.6/es/book.toml
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
[book]
|
||||
authors = ["Manuel Cillero"]
|
||||
language = "es"
|
||||
src = "src"
|
||||
title = "Guía de PageTop"
|
||||
|
||||
[output.html]
|
||||
theme = "../../theme"
|
||||
# The guides number the steps of each page themselves; the sidebar groups pages by kind.
|
||||
no-section-label = true
|
||||
|
||||
# The examples need PageTop: they cannot run in the Rust playground.
|
||||
[output.html.playground]
|
||||
runnable = false
|
||||
3
doc/v0.6/es/src/404.md
Normal file
3
doc/v0.6/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!
|
||||
76
doc/v0.6/es/src/SUMMARY.md
Normal file
76
doc/v0.6/es/src/SUMMARY.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
# Summary
|
||||
|
||||
[PageTop](intro.md)
|
||||
|
||||
# Tutoriales
|
||||
|
||||
- [Tu primera aplicación](tutorials/first-app.md)
|
||||
- [Recorrido por PageTop](tutorials/tour.md)
|
||||
- [Tareas del huerto con HTMX](tutorials/htmx-tasks.md)
|
||||
- [Guarda las tareas en una base de datos](tutorials/database.md)
|
||||
|
||||
# Guías prácticas
|
||||
|
||||
- [Páginas y componentes]()
|
||||
- [Añadir rutas](how-to/routes.md)
|
||||
- [Construir páginas](how-to/pages.md)
|
||||
- [Mostrar páginas de error](how-to/error-pages.md)
|
||||
- [Escribir HTML con `html!`](how-to/html.md)
|
||||
- [Usar componentes](how-to/components.md)
|
||||
- [Crear un componente](how-to/custom-components.md)
|
||||
- [Maquetar con Flex y Grid](how-to/layout.md)
|
||||
- [Añadir navegación](how-to/navigation.md)
|
||||
- [Crear y procesar formularios](how-to/forms.md)
|
||||
- [Subir y descargar archivos](how-to/uploads.md)
|
||||
- [Mostrar tablas ordenables y paginadas](how-to/tables.md)
|
||||
- [Interactividad con HTMX]()
|
||||
- [Añadir HTMX a una aplicación](how-to/htmx-setup.md)
|
||||
- [Cargar contenido bajo demanda](how-to/htmx-load.md)
|
||||
- [Buscar mientras se escribe](how-to/htmx-search.md)
|
||||
- [Validar un campo al vuelo](how-to/htmx-validation.md)
|
||||
- [Editar en línea](how-to/htmx-edit.md)
|
||||
- [Borrar con confirmación](how-to/htmx-delete.md)
|
||||
- [Ordenar y paginar sin recargar](how-to/htmx-tables.md)
|
||||
- [Cargar más al hacer *scroll*](how-to/htmx-infinite.md)
|
||||
- [Actualizar periódicamente](how-to/htmx-polling.md)
|
||||
- [Dirigir al navegador desde el servidor](how-to/htmx-responses.md)
|
||||
- [Datos y usuarios]()
|
||||
- [Conectar una base de datos](how-to/database.md)
|
||||
- [Añadir usuarios y permisos](how-to/users.md)
|
||||
- [Añadir páginas al panel de administración](how-to/admin.md)
|
||||
- [La aplicación]()
|
||||
- [Configurar la aplicación](how-to/configuration.md)
|
||||
- [Compartir un servicio entre rutas](how-to/services.md)
|
||||
- [Programar tareas periódicas](how-to/cron.md)
|
||||
- [Enviar correo electrónico](how-to/mail.md)
|
||||
- [Añadir *middleware*](how-to/middleware.md)
|
||||
- [Traducir la aplicación](how-to/localization.md)
|
||||
- [Servir recursos estáticos](how-to/assets.md)
|
||||
- [Probar rutas y componentes](how-to/testing.md)
|
||||
- [Registrar trazas](how-to/logging.md)
|
||||
- [Desplegar en producción](how-to/deployment.md)
|
||||
- [Extender PageTop]()
|
||||
- [Crear una extensión](how-to/extensions.md)
|
||||
- [Intervenir con acciones](how-to/actions.md)
|
||||
- [Crear un tema](how-to/themes.md)
|
||||
|
||||
# Referencia
|
||||
|
||||
- [Opciones de configuración](reference/configuration.md)
|
||||
- [Catálogo de componentes](reference/components.md)
|
||||
- [HTMX: atributos, cabeceras y respuestas](reference/htmx.md)
|
||||
- [Extensiones oficiales](reference/extensions.md)
|
||||
- [Referencia rápida](reference/cheatsheet.md)
|
||||
|
||||
# Explicación
|
||||
|
||||
- [Por qué PageTop](explanation/why.md)
|
||||
- [PageTop frente a otros *frameworks*](explanation/comparison.md)
|
||||
- [Arquitectura: del arranque a la respuesta](explanation/architecture.md)
|
||||
- [Componentes, temas y renderizado](explanation/rendering.md)
|
||||
- [HTML por la red: por qué HTMX](explanation/htmx.md)
|
||||
- [Si vienes de Axum](explanation/coming-from-axum.md)
|
||||
|
||||
---
|
||||
|
||||
[Preguntas frecuentes](faq.md)
|
||||
143
doc/v0.6/es/src/explanation/architecture.md
Normal file
143
doc/v0.6/es/src/explanation/architecture.md
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
# Arquitectura: del arranque a la respuesta
|
||||
|
||||
Una aplicación PageTop vive dos momentos distintos: el **arranque**, que ocurre una vez y prepara
|
||||
todo, y la **petición**, que ocurre miles de veces y debe ser rápida. Entender qué pasa en cada uno
|
||||
explica casi todas las decisiones de diseño de PageTop.
|
||||
|
||||
## Un árbol de extensiones
|
||||
|
||||
Una aplicación es un **árbol de extensiones**. En la raíz está la tuya; de ella cuelgan las que
|
||||
declara como dependencias, y de esas, las suyas:
|
||||
|
||||
```text
|
||||
MyApp <- root extension
|
||||
├── Bootsier <- theme
|
||||
├── User <- accounts and permissions
|
||||
│ ├── Admin
|
||||
│ ├── SeaORM <- database
|
||||
│ └── Htmx
|
||||
└── Blog <- your feature
|
||||
└── SeaORM <- the same one: each extension is registered once
|
||||
```
|
||||
|
||||
Este árbol es independiente de las dependencias de `Cargo.toml`: Cargo decide qué se **compila**;
|
||||
`dependencies()` decide qué se **activa** y en qué orden. Una extensión compilada pero que nadie
|
||||
declara no registra rutas ni ajustes.
|
||||
|
||||
Separar la extensión raíz en `src/lib.rs` y dejar `src/main.rs` con lo mínimo permite usar la
|
||||
aplicación como biblioteca, por ejemplo desde las pruebas:
|
||||
|
||||
```text
|
||||
my-app/
|
||||
├── Cargo.toml
|
||||
├── config/
|
||||
│ ├── common.toml <- common settings
|
||||
│ └── local.toml <- local settings (not versioned)
|
||||
└── src/
|
||||
├── lib.rs <- root extension
|
||||
├── main.rs <- startup
|
||||
└── locale/ <- translations
|
||||
├── en-US/
|
||||
└── es-ES/
|
||||
```
|
||||
|
||||
## El arranque
|
||||
|
||||
`Application::prepare()` sigue siempre los mismos pasos:
|
||||
|
||||
```text
|
||||
Application::prepare(&MyApp)
|
||||
1. banner and traces [log] settles how much is traced and where
|
||||
2. language and time zone the defaults of [app]
|
||||
3. register extensions walks the tree: dependencies first, each one once
|
||||
4. load settings every settings() section, validated
|
||||
5. default theme the one in [app] theme, or Basic with a warning
|
||||
6. register actions every actions(), sorted by weight
|
||||
7. initialize extensions every initialize(), dependencies first
|
||||
|
|
||||
v
|
||||
.run()
|
||||
8. build the server routes + middleware + static files
|
||||
9. start extensions every start(): background services, such as pagetop-cron
|
||||
10. serve requests until Ctrl+C or SIGTERM
|
||||
11. shut down extensions every shutdown(), in reverse order
|
||||
```
|
||||
|
||||
Tres consecuencias importantes:
|
||||
|
||||
- **Lo que falla, falla al arrancar.** Una clave mal escrita, un valor no válido, una base de datos
|
||||
que no responde o una migración rota detienen la aplicación antes de servir una sola petición,
|
||||
con un mensaje que explica la causa. Nunca hay una aplicación a medias en producción.
|
||||
- **Lo costoso se hace una vez.** Las traducciones, los ajustes, las acciones y los recursos
|
||||
estáticos se cargan o se registran al arrancar; en cada petición sólo se consultan.
|
||||
- **Las pruebas no lanzan nada en segundo plano.** Una prueba prepara la aplicación con
|
||||
`prepare()` y obtiene su servidor con `test()`, sin llamar a `run()`: hace los pasos 1 a 8, pero
|
||||
ni arranca los servicios de las extensiones ni ejecuta tareas programadas por su cuenta.
|
||||
|
||||
## La petición
|
||||
|
||||
Cuando llega una petición, recorre las capas que construyó `run()`:
|
||||
|
||||
```text
|
||||
request
|
||||
|
|
||||
v
|
||||
+------------------------------------------------------------+
|
||||
| cross-origin check (CSRF) -> 403 for a POST, PUT... |
|
||||
| from another origin |
|
||||
+------------------------------------------------------------+
|
||||
| static files (/static, /htmx...) -> served directly, |
|
||||
| without middleware |
|
||||
+------------------------------------------------------------+
|
||||
| middleware of the extensions (session, current user...) |
|
||||
| +------------------------------------------------------+ |
|
||||
| | router -> your handler | |
|
||||
| | Page::new(request) builds the Context: | |
|
||||
| | language, theme, user, zone | |
|
||||
| | .with_child(...) adds components, not HTML | |
|
||||
| | .render() the theme lays out the page | |
|
||||
| +------------------------------------------------------+ |
|
||||
+------------------------------------------------------------+
|
||||
|
|
||||
v
|
||||
response (complete HTML, or a fragment for HTMX)
|
||||
```
|
||||
|
||||
- La **comprobación de origen** rechaza con `403`, antes de llegar al *middleware* de las
|
||||
extensiones, las peticiones que pueden cambiar algo (`POST`, `PUT`...) y que el navegador indica
|
||||
que vienen de otro origen: es la protección contra CSRF, sin *tokens* en los formularios. Ver
|
||||
[Sin *tokens* contra CSRF](../how-to/forms.md#6-sin-tokens-contra-csrf).
|
||||
- Los **archivos estáticos** se registran después del *middleware*, así que no pasan por él:
|
||||
servir una hoja de estilos no resuelve sesiones ni consulta la base de datos.
|
||||
- El **middleware** de cada extensión (`configure_middleware()`) envuelve las rutas de **todas**
|
||||
las extensiones. Así, `pagetop-user` resuelve la sesión una vez y cualquier ruta sabe quién pide.
|
||||
- El ***handler*** es un *handler* de Axum normal. `Page::new(request)` crea el **contexto** de la
|
||||
petición, que viajará por todos los componentes: el idioma negociado, el tema, el usuario, la
|
||||
zona horaria, los recursos y los mensajes.
|
||||
|
||||
Qué pasa dentro de `render()` se explica en [Componentes, temas y renderizado](rendering.md).
|
||||
|
||||
## Sin estado mutable compartido
|
||||
|
||||
Los ajustes son de sólo lectura, las acciones se registran una vez y los componentes globales
|
||||
(`InRegion`) se **clonan** para cada página. Cada petición trabaja con su propio contexto y sus
|
||||
propias copias: lo que un componente cambia al renderizarse no afecta a otras peticiones. El estado
|
||||
que debe compartirse entre peticiones (datos, sesiones) vive en la base de datos o, si es tuyo, en
|
||||
tus propias estructuras.
|
||||
|
||||
## El preludio
|
||||
|
||||
Casi todo lo que necesitas está en un solo `use`:
|
||||
|
||||
```rust
|
||||
use pagetop::prelude::*;
|
||||
```
|
||||
|
||||
Trae los tipos principales (`Extension`, `Page`, `Component`, `Lc`...), los componentes base, las
|
||||
macros (`html!`, `include_locales!`...) y accesos directos a módulos como `web`, `trace`, `util` o
|
||||
`global`. Las extensiones tienen el suyo: `pagetop_htmx::prelude::*`, `pagetop_user::prelude::*`...
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Componentes, temas y renderizado](rendering.md).
|
||||
- [Si vienes de Axum](coming-from-axum.md): qué es igual y qué cambia.
|
||||
59
doc/v0.6/es/src/explanation/coming-from-axum.md
Normal file
59
doc/v0.6/es/src/explanation/coming-from-axum.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
# Si vienes de Axum
|
||||
|
||||
PageTop está construido **sobre** [Axum](https://docs.rs/axum) y [Tokio](https://tokio.rs), no al
|
||||
lado. Lo que sabes de Axum sigue valiendo: las rutas, los extractores, las respuestas y el
|
||||
*middleware* son los suyos, reexportados en `web`. PageTop añade lo que una aplicación web completa
|
||||
necesita encima, y una forma de organizarlo.
|
||||
|
||||
## Lo que se traduce directamente
|
||||
|
||||
| En Axum | En PageTop | Qué cambia |
|
||||
|---|---|---|
|
||||
| `Router::new().route(...)` | `configure_router()` de cada extensión | Cada extensión añade sus rutas al mismo `Router` |
|
||||
| `axum::routing::get`, `post`... | `web::get`, `web::post`... | Nada: son los mismos |
|
||||
| `Path`, `Query`, `Form`, `Json` | `web::Path`, `web::Query`, `web::Form`, `Json` | Nada |
|
||||
| `Request` | `HttpRequest` | Una vista clonable de la petición, que no consume el cuerpo y se puede pedir junto a cualquier extractor |
|
||||
| `impl IntoResponse` | `IntoResponse`, `Response` | Nada; `Markup` y `ErrorPage` también la implementan |
|
||||
| `Redirect::to(...)` | `Redirect::see_other(...)`, `found()`, `temporary()`... | Un constructor por código de estado |
|
||||
| `middleware::from_fn` | `web::middleware::from_fn` en `configure_middleware()` | Se aplica a las rutas de todas las extensiones |
|
||||
| `ServeDir` | `serve_static_files!` en `configure_static_files()` | Los archivos pueden ir dentro del binario |
|
||||
| `#[tokio::main]` | `#[pagetop::main]` | Prepara el *runtime* que usa PageTop |
|
||||
| `#[tokio::test]` | `#[pagetop::test]` | Igual, para las pruebas |
|
||||
| `State<T>` | Ajustes con `#[settings]`, estáticos propios | Ver abajo |
|
||||
|
||||
## Lo que PageTop añade
|
||||
|
||||
- **Páginas completas** con `Page`: el `<head>`, los recursos sin duplicados, el idioma, la
|
||||
dirección del texto y la estructura del tema.
|
||||
- **Componentes** con su HTML, sus estilos y su comportamiento, que se adaptan al tema activo.
|
||||
- **Temas intercambiables** desde la configuración.
|
||||
- **Configuración en cascada** con validación al arrancar.
|
||||
- **Traducciones** con Fluent, integradas en el binario.
|
||||
- **Extensiones** con dependencias y un orden de arranque garantizado, que se suman con una línea.
|
||||
- **Páginas de error** (403, 404, 500...) con el aspecto del sitio.
|
||||
|
||||
## El estado de la aplicación
|
||||
|
||||
En Axum, el estado compartido suele viajar con `State<T>`. En PageTop, cada extensión gestiona el
|
||||
suyo:
|
||||
|
||||
- La **configuración** se declara con `#[settings]` y se lee desde cualquier sitio con su estático
|
||||
(`SETTINGS.page_size`), sin pasarla de *handler* en *handler*.
|
||||
- Los **recursos** que se crean al arrancar (una conexión, un cliente HTTP, una caché) se
|
||||
inicializan en `initialize()` y se guardan en un estático (`OnceLock`, `LazyLock`). Así lo hace
|
||||
`pagetop-seaorm` con su `dbconn()`. Paso a paso en [Compartir un servicio entre
|
||||
rutas](../how-to/services.md).
|
||||
- Lo que depende de **cada petición** (el idioma, el usuario, el tema) está en el `Context` que crea
|
||||
`Page::new(request)` y que reciben todos los componentes.
|
||||
|
||||
## Mezclar código de Axum
|
||||
|
||||
`configure_router()` recibe y devuelve un `Router` de Axum, así que puedes añadirle cualquier cosa
|
||||
que Axum admita: rutas con capas propias, servicios de Tower, rutas anidadas o un `Router`
|
||||
existente con `merge()`. Una ruta que devuelve JSON convive sin problemas con las que devuelven
|
||||
páginas.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Arquitectura: del arranque a la respuesta](architecture.md).
|
||||
- [Tu primera aplicación](../tutorials/first-app.md).
|
||||
137
doc/v0.6/es/src/explanation/comparison.md
Normal file
137
doc/v0.6/es/src/explanation/comparison.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
# PageTop frente a otros *frameworks*
|
||||
|
||||
Rust tiene muy buenos *frameworks* web, y es justo preguntarse por qué elegir uno u otro. Esta
|
||||
página compara PageTop con los más conocidos, con sus puntos fuertes y también con lo que a PageTop
|
||||
todavía le falta.
|
||||
|
||||
A grandes rasgos hay dos familias. Los **modulares** (Actix Web, Axum, Poem) te dan las piezas
|
||||
básicas para atender peticiones y te dejan elegir el resto: base de datos, plantillas, usuarios. Los
|
||||
**completos** (Rocket en parte, Loco, Cot, Topcoat) traen de serie muchas de esas piezas y unas
|
||||
convenciones para encajarlas. PageTop está en la segunda familia, con un matiz: lo que trae lo
|
||||
organiza en **extensiones**, **componentes** y **temas**, y casi todo es opcional.
|
||||
|
||||
Ten en cuenta también la madurez: PageTop sigue en versiones 0.x, su API todavía cambia entre
|
||||
versiones y su comunidad es más pequeña que la de la mayoría de los *frameworks* de esta página.
|
||||
|
||||
## Tabla comparativa
|
||||
|
||||
| | PageTop | Rocket | Poem | Loco | Cot | Topcoat |
|
||||
|:--|:--|:--|:--|:--|:--|:--|
|
||||
| **Enfoque** | Completo, por extensiones | Completo en parte | Modular, con OpenAPI | Completo (como Rails) | Completo (como Django) | Completo, interfaz reactiva |
|
||||
| **Base** | Axum | Hyper y Tokio | Hyper y Tokio | Axum | Axum | Hyper y Tokio |
|
||||
| **HTML** | `html!` con componentes y temas | Tera, Handlebars o MiniJinja | A tu elección | Tera (u otro motor) | Askama (u otro motor) | `view!` con componentes |
|
||||
| **Interactividad** | HTMX (extensión) | A tu elección | A tu elección | HTMX en sus generadores | A tu elección | Reactividad propia; también HTMX, Alpine AJAX o Datastar |
|
||||
| **Base de datos** | SeaORM (extensión) | Varias, con su integración | A tu elección | SeaORM | ORM propio | Toasty, recomendado |
|
||||
| **Migraciones** | Escritas en Rust, aplicadas al arrancar | Herramientas externas | Herramientas externas | Generadas con su CLI | Generadas a partir de los modelos | Generadas a partir de los modelos (Toasty) |
|
||||
| **Usuarios y permisos** | Extensión (roles y permisos); CSRF en el núcleo | No | No (sesiones y CSRF) | Autenticación (JWT y claves de API) | Autenticación | Sesiones; autenticación prevista |
|
||||
| **Panel de administración** | Extensible, con formularios de ajustes | No | No | No | Generado a partir de los modelos | No |
|
||||
| **Traducciones** | Fluent, de serie | No | Fluent, opcional | Fluent, en su plantilla de proyecto | No | Fluent |
|
||||
| **Tareas en segundo plano y correo** | Tareas programadas y correo con cola persistente (extensiones); sin cola de trabajos genérica | No | No | Colas, tareas programadas y correo | Correo y caché | Correo; tareas en segundo plano previstas |
|
||||
|
||||
## PageTop frente a Rocket
|
||||
|
||||
Rocket es conocido por lo agradable que resulta escribir rutas con sus macros, por sus guardas de
|
||||
petición y por llevar la seguridad de tipos muy lejos. Trae de serie plantillas, *cookies* privadas,
|
||||
WebSocket, perfiles de configuración, pruebas e integración con varias bases de datos.
|
||||
|
||||
- **Elige Rocket si** te gusta su estilo de API y prefieres montar tú los usuarios, los permisos y
|
||||
la interfaz sobre esas piezas.
|
||||
- **Elige PageTop si** quieres que esas piezas vengan resueltas: usuarios y permisos, panel de
|
||||
administración, temas y traducciones.
|
||||
|
||||
## PageTop frente a Poem
|
||||
|
||||
[Poem](https://github.com/poem-web/poem) es un *framework* modular, como Axum o Actix Web, pero con
|
||||
muchas piezas opcionales que se activan por *features* (sesiones, CSRF, WebSocket, traducciones con
|
||||
Fluent...). Destaca por `poem-openapi`, que genera la especificación OpenAPI a partir de los tipos
|
||||
de la API, y por su soporte para gRPC.
|
||||
|
||||
- **Elige Poem si** construyes una API y quieres la documentación OpenAPI generada de serie, con
|
||||
Swagger UI u otros visores, o quieres servir también gRPC con el mismo *framework*.
|
||||
- **Elige PageTop si** vas a generar páginas: Poem no trae componentes, temas, usuarios ni panel de
|
||||
administración, y la interfaz queda en tus manos.
|
||||
|
||||
## PageTop frente a Loco
|
||||
|
||||
Loco se presenta como «Rust on Rails» y como el *framework* para quien trabaja en solitario:
|
||||
convenciones fuertes, una CLI que genera código y muchas piezas incluidas, también sobre Axum y
|
||||
SeaORM.
|
||||
|
||||
- **Elige Loco si** te gusta la filosofía de Rails, quieres generadores de código, o necesitas ya
|
||||
**colas de trabajos** genéricas que sobrevivan a un reinicio (en la base de datos o en Redis), que
|
||||
PageTop todavía no tiene. Las tareas programadas y el correo sí los tiene PageTop, con sus
|
||||
extensiones, y el correo puede guardarse en una cola persistente.
|
||||
- **Elige PageTop si** tu aplicación es sobre todo interfaz: los componentes tipados y los temas
|
||||
que pueden cambiar cualquier componente no tienen equivalente en Loco, que construye la interfaz
|
||||
con plantillas (sus generadores sí pueden crear vistas con HTMX).
|
||||
|
||||
## PageTop frente a summer-rs
|
||||
|
||||
[summer-rs](https://summer-rs.github.io) (antes spring-rs) se inspira en Spring Boot: un núcleo
|
||||
pequeño de *plugins* que integran piezas del ecosistema (Axum, SQLx, SeaORM, Redis, correo con
|
||||
lettre, tareas programadas, autenticación con Sa-Token, OpenTelemetry, gRPC...), configurados en
|
||||
TOML y con inyección de dependencias en tiempo de compilación.
|
||||
|
||||
- **Elige summer-rs si** construyes servicios o APIs y quieres tener ya integrados la caché, las
|
||||
colas o la observabilidad.
|
||||
- **Elige PageTop si** lo que construyes son páginas: summer-rs no trae plantillas, componentes,
|
||||
temas ni traducciones. La idea de los *plugins* es muy parecida a la de las extensiones; donde
|
||||
summer-rs inyecta componentes, PageTop guarda los servicios en estáticos (ve [Compartir un
|
||||
servicio entre rutas](../how-to/services.md)).
|
||||
|
||||
## PageTop frente a Cot
|
||||
|
||||
Cot toma la filosofía de Django: un ORM propio que genera las migraciones a partir de los modelos y
|
||||
un panel de administración que se construye solo.
|
||||
|
||||
- **Elige Cot si** te gusta Django y quieres un panel de administración con altas, bajas y
|
||||
modificaciones de tus modelos sin escribir nada, o una API JSON con su documentación OpenAPI y
|
||||
Swagger UI generadas.
|
||||
- **Elige PageTop si** prefieres SeaORM, quieres construir la interfaz con componentes y temas en
|
||||
lugar de plantillas, o necesitas traducciones. El panel de PageTop no genera páginas a partir de
|
||||
los modelos, pero cada extensión le añade las suyas, con sus permisos (ve [Añadir páginas al panel
|
||||
de administración](../how-to/admin.md)).
|
||||
|
||||
## PageTop frente a Topcoat
|
||||
|
||||
[Topcoat](https://tokio.rs/blog/2026-07-22-announcing-topcoat), del proyecto Tokio (lo firman Carl
|
||||
Lerche, creador de Tokio, y Julien Scholz), es el más parecido a PageTop en la forma de construir la
|
||||
interfaz: todo se renderiza en el servidor, con páginas y componentes escritos en Rust (`#[page]`,
|
||||
`#[component]` y la macro `view!`). Añade su propio sistema de reactividad, con señales cuyo código
|
||||
se compila a JavaScript y fragmentos de la página que se vuelven a renderizar en el servidor, y
|
||||
también se integra con HTMX, Alpine AJAX o Datastar. Es muy reciente: se presentó en julio de 2026
|
||||
y, como PageTop, avisa de que su API cambiará.
|
||||
|
||||
- **Elige Topcoat si** quieres reactividad en el navegador sin escribir JavaScript ni compilar a
|
||||
WebAssembly, o su biblioteca de componentes con Tailwind.
|
||||
- **Elige PageTop si** necesitas ya usuarios y permisos, panel de administración o tareas
|
||||
programadas, que en Topcoat todavía no existen o están en su hoja de ruta, o temas capaces de
|
||||
cambiar el aspecto de cualquier componente sin tocar la aplicación.
|
||||
|
||||
## ¿Y Axum o Actix Web?
|
||||
|
||||
No están en la tabla porque casi todas sus filas dirían «A tu elección» o «No»: son la base sobre
|
||||
la que se construye una aplicación, no la aplicación hecha. PageTop **está construido sobre Axum**,
|
||||
así que comparten rutas, extractores y respuestas, y lo que sabes de Axum lo puedes usar en PageTop
|
||||
(lo cuenta [Si vienes de Axum](coming-from-axum.md)). Actix Web es maduro y uno de los más rápidos
|
||||
que existen, aunque Rust y Axum ya dan un rendimiento de sobra para la inmensa mayoría de
|
||||
aplicaciones de gestión. Son buena elección si quieres controlar cada pieza, construyes una API o un
|
||||
microservicio sin interfaz, o ya tienes código sobre alguno de ellos. Si vas a generar páginas,
|
||||
PageTop te ahorra juntar plantillas, traducciones, recursos estáticos, configuración y extensiones,
|
||||
y sigues teniendo Axum debajo cuando lo necesites.
|
||||
|
||||
## ¿Y Leptos o Dioxus?
|
||||
|
||||
Leptos y Dioxus son *frameworks* **de pila completa** con reactividad fina: la interfaz se compila a
|
||||
WebAssembly y se ejecuta en el navegador, y puede renderizarse antes en el servidor e hidratarse
|
||||
después. Dioxus, además, lleva la misma aplicación al escritorio y al móvil. Es el modelo contrario
|
||||
al de PageTop: aquí la interfaz vive en el servidor y HTMX sólo intercambia fragmentos de HTML. Si
|
||||
tu aplicación necesita mucha lógica en el navegador, funcionar sin conexión o ejecutarse también
|
||||
fuera de él, mira hacia ellos (lo explica también
|
||||
[Por qué PageTop](why.md#cuándo-no-es-la-mejor-opción)).
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Por qué PageTop](why.md): las ideas detrás del diseño.
|
||||
- [Si vienes de Axum](coming-from-axum.md): lo que ya sabes y lo que cambia.
|
||||
- [HTML por la red: por qué HTMX](htmx.md).
|
||||
68
doc/v0.6/es/src/explanation/htmx.md
Normal file
68
doc/v0.6/es/src/explanation/htmx.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# HTML por la red: por qué HTMX
|
||||
|
||||
PageTop genera HTML en el servidor. Para la interactividad podría haber elegido un *framework* de
|
||||
JavaScript que pidiera JSON y pintara la interfaz en el navegador. Elige [HTMX](https://htmx.org)
|
||||
porque encaja con todo lo demás: el servidor sigue generando el HTML, y el navegador sólo decide
|
||||
cuándo pedirlo y dónde ponerlo.
|
||||
|
||||
## Dos formas de hacer una interfaz interactiva
|
||||
|
||||
| | Aplicación de una sola página (SPA) | HTMX |
|
||||
|---|---|---|
|
||||
| El servidor envía | JSON | HTML |
|
||||
| La interfaz se genera en | El navegador, con JavaScript | El servidor, con los mismos componentes que la página |
|
||||
| Estado de la interfaz | Duplicado: en el servidor y en el cliente | En el servidor |
|
||||
| Lo que hay que mantener | Dos aplicaciones y la API que las une | Una aplicación |
|
||||
| Validación | En los dos lados | En el servidor |
|
||||
| Sin JavaScript | No funciona | Funciona, con recargas completas, si se diseña así |
|
||||
|
||||
Con HTMX, una ruta que responde a una interacción es una ruta como las demás: recibe la petición,
|
||||
consulta lo que haga falta y devuelve HTML. No hay que diseñar una API, ni serializar, ni mantener
|
||||
en sincronía dos modelos de datos.
|
||||
|
||||
## Por qué encaja con PageTop
|
||||
|
||||
- **Los mismos componentes.** El fragmento que devuelve una ruta para HTMX se genera con los mismos
|
||||
componentes, el mismo tema y las mismas traducciones que la página entera. No hay una segunda
|
||||
versión de la interfaz en JavaScript.
|
||||
- **Los atributos son sólo atributos.** Los componentes de PageTop no conocen HTMX. Aceptan
|
||||
atributos con `with_prop()`, y `hx-get` es uno más. Por eso HTMX es una extensión opcional, y
|
||||
un componente sirve igual con HTMX o sin él.
|
||||
- **Lo que se prueba es HTML.** Una ruta para HTMX se prueba como cualquier otra: se envía la
|
||||
petición y se comprueba el HTML y las cabeceras de la respuesta. El comportamiento en el navegador
|
||||
lo declaran los atributos, sin lógica propia que probar.
|
||||
- **Un solo lenguaje.** La lógica de la interfaz está en Rust, comprobada por el compilador.
|
||||
|
||||
## Mejora progresiva
|
||||
|
||||
Una página bien hecha con HTMX funciona **antes** de que HTMX llegue: los enlaces llevan su `href` y
|
||||
los formularios su `action`. HTMX intercepta esa navegación y la convierte en una petición parcial,
|
||||
y la ruta responde según quién llame:
|
||||
|
||||
```text
|
||||
+--> HX-Request: true --> only the fragment
|
||||
GET /plants?q=to ------+
|
||||
+--> (no header) --> the whole page
|
||||
```
|
||||
|
||||
Así, la misma URL sirve para buscar sin recargar, para compartir el resultado y para recargar la
|
||||
página. Las guías de [búsqueda](../how-to/htmx-search.md) y de [tablas](../how-to/htmx-tables.md) lo
|
||||
aplican.
|
||||
|
||||
## Cuándo no es la herramienta adecuada
|
||||
|
||||
HTMX resuelve muy bien las interfaces de gestión, los formularios, los listados, los paneles y la
|
||||
mayoría de webs con contenido. No es la mejor opción para:
|
||||
|
||||
- interfaces que deben funcionar **sin conexión**;
|
||||
- interacciones de **alta frecuencia** en el propio navegador, como un editor gráfico, un juego o
|
||||
arrastrar elementos con respuesta inmediata a cada píxel;
|
||||
- aplicaciones donde casi todo ocurre en el cliente y el servidor apenas interviene.
|
||||
|
||||
Para esos casos puntuales, nada impide añadir JavaScript propio a una página o a un componente:
|
||||
PageTop lo gestiona como cualquier otro recurso.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Tareas del huerto con HTMX](../tutorials/htmx-tasks.md): el enfoque en la práctica.
|
||||
- [HTMX: atributos, cabeceras y respuestas](../reference/htmx.md).
|
||||
109
doc/v0.6/es/src/explanation/rendering.md
Normal file
109
doc/v0.6/es/src/explanation/rendering.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
# Componentes, temas y renderizado
|
||||
|
||||
En PageTop, una página no se escribe: se **compone**. El *handler* añade componentes; el tema decide
|
||||
dónde va cada uno y cómo se ve; las extensiones pueden intervenir en el camino. Esta página explica
|
||||
quién decide qué, y en qué orden.
|
||||
|
||||
## Componentes, no HTML
|
||||
|
||||
`with_child()` no añade HTML a la página, sino **un componente**: un valor Rust con sus datos.
|
||||
El HTML se genera más tarde, al llamar a `render()`, cuando ya se sabe:
|
||||
|
||||
- el **idioma** de quien visita, para resolver cada `Lc`;
|
||||
- el **tema** activo, que puede ajustar o reescribir el componente;
|
||||
- el **usuario**, para mostrar u ocultar lo que corresponda;
|
||||
- los **recursos** que necesita cada componente, para ponerlos en el `<head>`.
|
||||
|
||||
Por eso un componente no debe guardar HTML ya generado: guarda los datos (un `Lc`, una ruta, otros
|
||||
componentes) y los convierte en HTML al renderizarse.
|
||||
|
||||
## Regiones y plantillas
|
||||
|
||||
Un tema reparte la página en **regiones** (cabecera, contenido, barra lateral, pie...) según una
|
||||
**plantilla**. Los componentes llegan a una región por tres caminos:
|
||||
|
||||
| Camino | Alcance |
|
||||
|---|---|
|
||||
| `page.with_child(c)` / `with_child_in(®ion, c)` | Sólo esta página |
|
||||
| `InRegion::Global(®ion).add(c)` | Todas las páginas, con cualquier tema |
|
||||
| `InRegion::ForTheme(&theme, ®ion).add(c)` | Todas las páginas, sólo con ese tema |
|
||||
|
||||
Las regiones de `CoreRegions` (`Header`, `Content`, `Aside`, `Footer`) existen en cualquier tema,
|
||||
así que una extensión que las use funciona con todos. Un tema puede definir más.
|
||||
|
||||
## El renderizado de una página
|
||||
|
||||
`Page::render()` sigue este orden:
|
||||
|
||||
```text
|
||||
Page::render()
|
||||
1. theme: before_render_page_body(page) the theme adds its own assets
|
||||
2. extensions: BeforeRenderBody e.g. HTMX adds its script
|
||||
3. <body>: the theme renders the regions every component, see below
|
||||
4. theme: after_render_page_body(page)
|
||||
5. extensions: AfterRenderBody
|
||||
6. deferred: postponed components, in place e.g. the messages of Content
|
||||
7. <head>: title, metadata and every asset collected so far
|
||||
```
|
||||
|
||||
El `<head>` se genera **al final**: así recoge los estilos y *scripts* que los componentes
|
||||
añadieron al contexto mientras se renderizaban. Un componente que sólo aparece en algunas páginas
|
||||
sólo carga sus recursos en esas páginas, y una vez aunque aparezca muchas veces.
|
||||
|
||||
Un componente puede pedir que se le **aplace** (`is_deferred()` devuelve `true`): en el paso 3 deja
|
||||
una marca en su sitio y se renderiza en el 6, cuando ya está hecho el resto. Se aplaza el momento,
|
||||
no la posición: se muestra donde estaba. Así funciona el `Messages` con el que empieza la región
|
||||
`Content`: aunque aparece al principio, recoge los avisos que añadan los componentes de toda la
|
||||
página. Si un componente aplazado no genera nada, la marca, un comentario HTML, se queda en su
|
||||
sitio; por eso los temas ocultan las regiones vacías con el selector `.region:empty`.
|
||||
|
||||
## El renderizado de un componente
|
||||
|
||||
Cada componente, en cada región, pasa por estos pasos:
|
||||
|
||||
```text
|
||||
component.render(cx)
|
||||
1. is_renderable(cx)? no -> nothing is rendered
|
||||
2. setup(cx) the component adjusts its own state
|
||||
3. BeforeRender<C> extensions adjust it (add classes, change texts...)
|
||||
4. for the active theme, then its parent, and so on:
|
||||
setup_component() the theme adjusts it
|
||||
render_component() the theme may render it its own way -> done
|
||||
5. prepare(cx) if no theme rendered it, the component does
|
||||
6. AfterRender<C> extensions react
|
||||
7. TransformMarkup<C> extensions retouch the final HTML
|
||||
```
|
||||
|
||||
Tres ideas salen de aquí:
|
||||
|
||||
- **El componente propone, el tema dispone.** El componente define sus datos y un HTML por defecto;
|
||||
el tema puede retocar los datos (`setup_component()`) o reemplazar el HTML entero
|
||||
(`render_component()`). Por eso los componentes exponen sus datos con *getters*: el tema los lee
|
||||
sin depender de sus detalles internos.
|
||||
- **Los temas se heredan.** Si el tema activo no reescribe un componente, se pregunta a su padre, y
|
||||
así hasta llegar al HTML del propio componente. Un tema hijo sólo cambia lo que necesita.
|
||||
- **Las extensiones no se pisan.** Varias acciones del mismo tipo se ejecutan en orden de peso, y
|
||||
cada `TransformMarkup` recibe el HTML que dejó la anterior.
|
||||
|
||||
Si `prepare()` devuelve un error, la página no se cae: se registra una traza con el componente y la
|
||||
ruta, y se pinta un contenido de reserva en su lugar.
|
||||
|
||||
## `setup()` prepara, `prepare()` pinta
|
||||
|
||||
`setup()` es síncrono y recibe el componente mutable: es el sitio para calcular clases o ajustar
|
||||
datos. `prepare()` es asíncrono y recibe el componente sin poder modificarlo: es el sitio para
|
||||
consultar una base de datos o un servicio y generar el HTML. Separarlos permite que las acciones y
|
||||
el tema actúen **entre** los dos, sobre un componente ya ajustado.
|
||||
|
||||
## Fragmentos para HTMX
|
||||
|
||||
Un componente también se renderiza fuera de una página, con `component.render(&mut cx)`, para
|
||||
devolverlo como fragmento a [HTMX](htmx.md). Pasa por los mismos pasos, con el mismo tema y las
|
||||
mismas acciones, así que el fragmento es idéntico a como se vería dentro de la página. Lo único que
|
||||
no tiene es `<head>`: los recursos que el componente añada al contexto no llegan al navegador, y la
|
||||
página que recibe el fragmento debe cargarlos ya.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Crear un componente](../how-to/custom-components.md).
|
||||
- [Crear un tema](../how-to/themes.md) e [Intervenir con acciones](../how-to/actions.md).
|
||||
62
doc/v0.6/es/src/explanation/why.md
Normal file
62
doc/v0.6/es/src/explanation/why.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
# Por qué PageTop
|
||||
|
||||
Durante años, la web se construyó así: el servidor genera HTML, el navegador lo muestra y un poco
|
||||
de JavaScript lo hace más ágil. Funcionaba, se entendía y cualquiera podía inspeccionarlo. Luego
|
||||
llegaron las aplicaciones de una sola página, los *frameworks* isomórficos y los *builds* de
|
||||
*frontend* con cientos de dependencias.
|
||||
|
||||
PageTop apuesta por volver a lo esencial, pero con herramientas de hoy:
|
||||
|
||||
| La web clásica | Lo que añade PageTop |
|
||||
|---|---|
|
||||
| HTML generado en el servidor | Generado con código Rust comprobado por el compilador |
|
||||
| Plantillas sueltas | Componentes tipados, configurables y reutilizables |
|
||||
| *Plugins* con efectos inesperados | Extensiones con dependencias declaradas y orden de arranque garantizado |
|
||||
| Temas que se pelean con el contenido | Temas que deciden cómo se pinta cada componente |
|
||||
| Despliegue de muchos archivos | Un binario con los recursos dentro |
|
||||
|
||||
## Cuatro ideas, nada más
|
||||
|
||||
Todo PageTop gira alrededor de cuatro conceptos. Los verás una y otra vez en esta guía:
|
||||
|
||||
- **Extensiones.** Unidades de funcionalidad. Tu aplicación es una extensión, y las que añadas
|
||||
(base de datos, usuarios, un tema...) también lo son.
|
||||
- **Componentes.** Piezas de interfaz que encapsulan HTML, CSS y JavaScript. Se combinan como
|
||||
bloques para formar páginas.
|
||||
- **Temas.** Extensiones especiales que dan el aspecto: maquetan la página por regiones y pueden
|
||||
ajustar o reescribir cualquier componente.
|
||||
- **Acciones.** Puntos de enganche: permiten que una extensión modifique lo que hace otra sin
|
||||
tocar su código.
|
||||
|
||||
## Lo que hay debajo
|
||||
|
||||
PageTop no reinventa la rueda; reúne piezas consolidadas del ecosistema Rust:
|
||||
|
||||
- [Axum](https://docs.rs/axum) y [Tokio](https://tokio.rs) para el servidor web asíncrono.
|
||||
- [Maud](https://maud.lambda.xyz) para escribir HTML dentro de Rust.
|
||||
- [Fluent](https://projectfluent.org) para las traducciones.
|
||||
- [config-rs](https://docs.rs/config) para la configuración en archivos TOML.
|
||||
- [tracing](https://docs.rs/tracing) para las trazas.
|
||||
|
||||
Y se apoya en extensiones opcionales para todo lo demás: [Bootstrap](https://getbootstrap.com) como
|
||||
tema, [HTMX](https://htmx.org) para la interactividad o [SeaORM](https://www.sea-ql.org/SeaORM)
|
||||
para las bases de datos.
|
||||
|
||||
## Cuándo no es la mejor opción
|
||||
|
||||
PageTop está pensado para aplicaciones web generadas en el servidor: gestión, portales, intranets,
|
||||
sitios con contenido. Probablemente **no** sea lo que buscas si:
|
||||
|
||||
- necesitas una aplicación que funcione **sin conexión**, o casi toda su lógica vive en el
|
||||
navegador;
|
||||
- sólo quieres una **API** JSON, sin páginas: Axum a secas es más directo;
|
||||
- necesitas **estabilidad** de API a largo plazo hoy mismo: PageTop todavía cambia entre versiones
|
||||
hasta la 1.0.
|
||||
|
||||
Para todo lo demás, sigue leyendo: [HTML por la red: por qué HTMX](htmx.md) explica cómo cubre
|
||||
PageTop la interactividad sin un *frontend* aparte.
|
||||
|
||||
## Licencia
|
||||
|
||||
PageTop es software libre con doble licencia **MIT o Apache 2.0**, a tu elección. Puedes usarlo en
|
||||
proyectos abiertos o cerrados.
|
||||
157
doc/v0.6/es/src/faq.md
Normal file
157
doc/v0.6/es/src/faq.md
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
# Preguntas frecuentes
|
||||
|
||||
## Desarrollo
|
||||
|
||||
**¿En qué se diferencia PageTop de Loco, Cot o Axum?**
|
||||
|
||||
En que organiza la aplicación en extensiones, componentes y temas, y genera la interfaz en el
|
||||
servidor con HTMX para la interactividad. La comparación completa, con lo que a PageTop todavía le
|
||||
falta, está en [PageTop frente a otros *frameworks*](explanation/comparison.md).
|
||||
|
||||
**¿Cómo reinicio la aplicación sola cada vez que cambio el código?**
|
||||
|
||||
Con una herramienta que vigile los archivos, como [watchexec](https://github.com/watchexec/watchexec):
|
||||
|
||||
```sh
|
||||
watchexec -r -e rs,toml,ftl -- cargo run
|
||||
```
|
||||
|
||||
Reinicia el servidor al cambiar el código, la configuración o las traducciones.
|
||||
[bacon](https://dystroy.org/bacon/) es otra buena opción.
|
||||
|
||||
**¿Puedo cambiar el CSS sin recompilar?**
|
||||
|
||||
Sí. Si publicas tus archivos con `serve_static_files!(router, ["./static", app] => "/static")`,
|
||||
mientras el directorio `static/` exista se sirven desde el disco: editas, recargas el navegador y
|
||||
ves el cambio. En producción, sin ese directorio, se sirven desde el binario. Ver [Servir recursos
|
||||
estáticos](how-to/assets.md).
|
||||
|
||||
**¿Cómo cambio el puerto?**
|
||||
|
||||
En `config/local.toml`, sin recompilar:
|
||||
|
||||
```toml
|
||||
[server]
|
||||
bind_port = 3000
|
||||
```
|
||||
|
||||
**Mi aplicación no arranca después de tocar la configuración.**
|
||||
|
||||
Es a propósito: una clave desconocida o un valor no válido detienen el arranque. El mensaje dice la
|
||||
sección y la clave. Compara con las [opciones de configuración](reference/configuration.md).
|
||||
|
||||
**¿Por qué los enlaces de mi página añaden `?lang=es`?**
|
||||
|
||||
Porque el visitante eligió idioma con `?lang=es` y ése no es el idioma por defecto. Los enlaces
|
||||
internos lo conservan para que no lo pierda al navegar. Si construyes las URL con `cx.route()` o
|
||||
pasas rutas a los componentes, PageTop se encarga solo. Ver [Añadir
|
||||
navegación](how-to/navigation.md#enlaces-que-conservan-el-idioma).
|
||||
|
||||
## Interfaz
|
||||
|
||||
**¿Puedo usar mi propio CSS, o Tailwind?**
|
||||
|
||||
Sí. Puedes añadir hojas de estilo a cualquier página o componente, o crear un tema que las cargue
|
||||
en todas. Los componentes usan clases propias y el tema decide cómo se ven; un tema hijo puede
|
||||
traducir esas clases a las de tu *framework* CSS. Ver [Crear un tema](how-to/themes.md).
|
||||
|
||||
**¿Cómo añado JavaScript propio?**
|
||||
|
||||
Como un recurso más: `JavaScript::defer("/static/js/app.js")` en una página o un componente, o
|
||||
`JavaScript::on_load()` para código que se ejecuta cuando el DOM está listo. Ver [Construir
|
||||
páginas](how-to/pages.md#4-añade-estilos-y-scripts).
|
||||
|
||||
**Mi fragmento de HTMX no aparece en la página.**
|
||||
|
||||
Las causas habituales, en este orden:
|
||||
|
||||
1. La ruta responde con un código **4xx o 5xx**: HTMX no coloca esas respuestas. Usa 200 para los
|
||||
errores que el usuario deba ver.
|
||||
2. El **destino** no existe: revisa el selector de `hx-target`. Si el fragmento sustituyó al propio
|
||||
destino (`outerHTML`) sin incluir su `id`, la siguiente petición ya no lo encuentra.
|
||||
3. Un atributo **heredado** de un elemento padre (`hx-swap`, `hx-target`) cambia el comportamiento.
|
||||
|
||||
En la pestaña *Red* de las herramientas del navegador ves la petición, su código y el HTML
|
||||
recibido.
|
||||
|
||||
**¿Puedo tener una API JSON en la misma aplicación?**
|
||||
|
||||
Sí. Una ruta puede devolver `Json<T>` con cualquier tipo serializable, junto a las que devuelven
|
||||
páginas. Ver [Añadir rutas](how-to/routes.md#4-elige-la-respuesta).
|
||||
|
||||
## Datos
|
||||
|
||||
**¿Qué bases de datos admite?**
|
||||
|
||||
PostgreSQL, MySQL (y MariaDB) y SQLite, a través de `pagetop-seaorm`. El código es el mismo para
|
||||
las tres; cambian la *feature* y la configuración. Ver [Conectar una base de
|
||||
datos](how-to/database.md).
|
||||
|
||||
**¿Puedo escribir SQL a mano?**
|
||||
|
||||
Sí. `fetch_all()` y `fetch_one()` ejecutan consultas construidas con `db::query`, y `execute()`
|
||||
sentencias que modifican datos. Ver [Escribe SQL a mano](how-to/database.md#8-escribe-sql-a-mano).
|
||||
|
||||
**¿Cómo muestro una página 404 o 500 con el aspecto del sitio?**
|
||||
|
||||
Devuelve `Err(ErrorPage::NotFound(Some(request)))` (o la variante que toque) desde el *handler*. Ver
|
||||
[Mostrar páginas de error](how-to/error-pages.md).
|
||||
|
||||
**¿Cómo comprimo las respuestas o limito el tamaño de lo que se envía?**
|
||||
|
||||
Con las capas de `tower-http` en `configure_middleware()`. Ver [Añadir
|
||||
*middleware*](how-to/middleware.md).
|
||||
|
||||
**¿Puedo programar tareas periódicas o enviar correos?**
|
||||
|
||||
Sí, con dos extensiones oficiales: `pagetop-cron` ejecuta trabajos en segundo plano según una
|
||||
expresión cron o a intervalos (ve [Programar tareas periódicas](how-to/cron.md)), y `pagetop-mail`
|
||||
envía correo (ve [Enviar correo electrónico](how-to/mail.md)), con una cola opcional
|
||||
que guarda los correos en la base de datos y reintenta los que fallan. Lo que todavía no tiene
|
||||
PageTop es una cola de trabajos genérica que sobreviva a un reinicio, como las de Loco (ve la
|
||||
[comparación con otros *frameworks*](explanation/comparison.md)).
|
||||
|
||||
**¿Tengo que usar una base de datos?**
|
||||
|
||||
No. Sólo la necesitan las extensiones que la usan, como `pagetop-user`. Una aplicación sin datos
|
||||
persistentes, o que los guarda en otro sitio, funciona igual.
|
||||
|
||||
## Producción
|
||||
|
||||
**¿Necesito Cargo o Rust en el servidor?**
|
||||
|
||||
No. El binario de `cargo build --release` lleva dentro los estilos, los *scripts*, las imágenes y
|
||||
las traducciones. En el servidor sólo necesita, a su lado, el directorio `config/`. Ver [Desplegar
|
||||
en producción](how-to/deployment.md).
|
||||
|
||||
**¿Está listo para producción?**
|
||||
|
||||
PageTop está en desarrollo activo y su API puede cambiar entre versiones hasta la 1.0. Se apoya en
|
||||
piezas maduras del ecosistema (Axum, Tokio, SeaORM, Fluent), pero conviene evaluarlo con tus
|
||||
propios requisitos antes de llevarlo a un sistema crítico.
|
||||
|
||||
**¿Necesito *tokens* CSRF en los formularios?**
|
||||
|
||||
No. PageTop rechaza con `403` las peticiones que pueden cambiar algo (`POST`, `PUT`...) cuando el
|
||||
navegador indica que vienen de otro origen, sin campos ocultos ni *cookies* adicionales. Sólo debes
|
||||
cuidar que ningún `GET` cambie nada. Ver [Sin *tokens* contra
|
||||
CSRF](how-to/forms.md#6-sin-tokens-contra-csrf).
|
||||
|
||||
**Un formulario responde con 403 en producción.**
|
||||
|
||||
Las causas habituales, en este orden:
|
||||
|
||||
1. El formulario está en **otro origen** (otro dominio, subdominio o puerto). Si es una aplicación
|
||||
tuya, añade su origen a `trusted_origins` de `[server]`.
|
||||
2. El **proxy inverso** cambia la cabecera `Host`. Conserva la original (`proxy_set_header Host
|
||||
$host;` en nginx). Ver [Detrás de un proxy
|
||||
inverso](how-to/deployment.md#5-detrás-de-un-proxy-inverso).
|
||||
3. Falta un **permiso**: el 403 es de la aplicación, no de la protección contra CSRF.
|
||||
|
||||
Las trazas lo distinguen: cada petición rechazada por venir de otro origen deja un aviso con la
|
||||
ruta y las cabeceras `Sec-Fetch-Site` y `Origin` recibidas.
|
||||
|
||||
**¿Cómo se detiene sin perder peticiones?**
|
||||
|
||||
Con `Ctrl+C` o con `SIGTERM` (lo que envían `systemd` y Docker), PageTop deja de aceptar
|
||||
conexiones, termina las peticiones en curso y vuelca las trazas pendientes.
|
||||
118
doc/v0.6/es/src/how-to/actions.md
Normal file
118
doc/v0.6/es/src/how-to/actions.md
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
# Intervenir con acciones
|
||||
|
||||
**Objetivo:** cambiar lo que hace otra extensión (cómo se ve un componente, qué HTML genera, qué
|
||||
lleva cada página) sin tocar su código.
|
||||
|
||||
Una **acción** permite a una extensión intervenir en lo que hace otra sin tocar su código: ajustar
|
||||
un componente antes de pintarlo, retocar su HTML o añadir algo a todas las páginas.
|
||||
|
||||
Se declaran en `actions()` con la macro `actions!`. PageTop las registra una sola vez al arrancar.
|
||||
|
||||
## 1. Ajusta un componente antes de renderizarlo
|
||||
|
||||
`BeforeRender<C>` recibe el componente (mutable) y el contexto, justo antes de que se pinte. Por
|
||||
ejemplo, añadir una clase a **todos** los botones de la aplicación:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
pub struct RoundButtons;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for RoundButtons {
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![action::component::BeforeRender::<Button>::new(round)]
|
||||
}
|
||||
}
|
||||
|
||||
fn round(button: &mut Button, _cx: &mut Context) {
|
||||
button.alter_prop(PropsOp::add_classes("rounded-pill"));
|
||||
}
|
||||
```
|
||||
|
||||
Para actuar sólo sobre un componente concreto, fíltralo por su identificador:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn highlight(button: &mut Button, _cx: &mut Context) {}
|
||||
# fn f() -> Vec<ActionBox> {
|
||||
actions![
|
||||
action::component::BeforeRender::<Button>::new(highlight).filter_by_referer_id("buy"),
|
||||
]
|
||||
# }
|
||||
```
|
||||
|
||||
## 2. Retoca el HTML final
|
||||
|
||||
`TransformMarkup<C>` recibe el HTML ya generado y devuelve el nuevo. Si hay varias, se encadenan:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
pub struct Marker;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Marker {
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![action::component::TransformMarkup::<Block>::new(mark_block)]
|
||||
}
|
||||
}
|
||||
|
||||
fn mark_block(_block: &Block, _cx: &Context, markup: Markup) -> Markup {
|
||||
html! {
|
||||
div class="marked-block" { (markup) }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`AfterRender<C>` se ejecuta tras renderizar, por si sólo necesitas reaccionar (registrar algo,
|
||||
por ejemplo).
|
||||
|
||||
## 3. Interviene en todas las páginas
|
||||
|
||||
`BeforeRenderBody` y `AfterRenderBody` reciben la página entera. Así añade la extensión HTMX su
|
||||
*script* a todas las páginas:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
pub struct Analytics;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Analytics {
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![action::page::BeforeRenderBody::new(add_script)]
|
||||
}
|
||||
}
|
||||
|
||||
fn add_script(page: &mut Page) {
|
||||
page.alter_assets(JavaScript::defer("/static/js/analytics.js"));
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Decide el orden
|
||||
|
||||
Las acciones de un mismo tipo se ejecutan por **peso** (de menor a mayor; admite negativos) y,
|
||||
a igualdad de peso, por orden de registro:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn first(b: &mut Button, cx: &mut Context) {}
|
||||
# fn f() -> Vec<ActionBox> {
|
||||
actions![action::component::BeforeRender::<Button>::new(first).with_weight(-10)]
|
||||
# }
|
||||
```
|
||||
|
||||
## Resumen
|
||||
|
||||
| Acción | Recibe | Momento |
|
||||
|---|---|---|
|
||||
| `component::BeforeRender<C>` | `&mut C`, `&mut Context` | Antes de renderizar `C` |
|
||||
| `component::AfterRender<C>` | `&mut C`, `&mut Context` | Después de renderizar `C` |
|
||||
| `component::TransformMarkup<C>` | `&C`, `&Context`, `Markup` | Para sustituir el HTML de `C` |
|
||||
| `page::BeforeRenderBody` | `&mut Page` | Antes de renderizar el `<body>` |
|
||||
| `page::AfterRenderBody` | `&mut Page` | Después de renderizar el `<body>` |
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Crear un tema](themes.md): un tema puede hacer lo mismo para todos los componentes.
|
||||
- [Componentes, temas y renderizado](../explanation/rendering.md): en qué momento exacto actúa cada
|
||||
acción.
|
||||
400
doc/v0.6/es/src/how-to/admin.md
Normal file
400
doc/v0.6/es/src/how-to/admin.md
Normal file
|
|
@ -0,0 +1,400 @@
|
|||
# Añadir páginas al panel de administración
|
||||
|
||||
**Objetivo:** dar a tu extensión su sitio en el panel `/admin`: una página de ajustes que el panel
|
||||
construye y guarda por ti, y una página propia con tu contenido, cada una protegida por su permiso.
|
||||
|
||||
El panel lo aporta `pagetop-admin`. No tienes que montarlo: llega con
|
||||
[`pagetop-user`](users.md), que lo necesita para administrar usuarios y roles. Tu extensión sólo
|
||||
**declara** sus páginas, y el panel las coloca en su sección, las enlaza desde el inicio del panel
|
||||
(*dashboard*) y las muestra sólo a quien tenga permiso.
|
||||
|
||||
## 1. Añade la dependencia
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
pagetop-admin = { git = "https://git.cillero.es/manuelcillero/pagetop" }
|
||||
pagetop-user = { git = "https://git.cillero.es/manuelcillero/pagetop" }
|
||||
pagetop-seaorm = { git = "https://git.cillero.es/manuelcillero/pagetop", features = ["sqlite"] }
|
||||
```
|
||||
|
||||
Tu extensión sigue dependiendo sólo de `pagetop_user::User`, como en [Añadir usuarios y
|
||||
permisos](users.md); el *crate* `pagetop-admin` hace falta para usar sus tipos.
|
||||
|
||||
Ese es el `Cargo.toml` de la **aplicación**, la única que elige el motor de base de datos (aquí
|
||||
SQLite) para todas sus extensiones. Si escribes una extensión aparte, declara `pagetop-admin` y
|
||||
`pagetop-user` igual, pero sin `pagetop-seaorm` (ve [Elige el motor](database.md#1-elige-el-motor)).
|
||||
|
||||
## 2. Define el permiso de cada página
|
||||
|
||||
Cada página del panel exige un permiso. Decláralo como cualquier otro:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
#[derive(Clone, Copy, Debug)]
|
||||
enum GardenPermission {
|
||||
Configure,
|
||||
SeeHarvest,
|
||||
}
|
||||
|
||||
impl Permission for GardenPermission {
|
||||
fn key(&self) -> CowStr {
|
||||
match self {
|
||||
Self::Configure => "garden.configure".into(),
|
||||
Self::SeeHarvest => "garden.see_harvest".into(),
|
||||
}
|
||||
}
|
||||
|
||||
fn label(&self) -> Lc {
|
||||
match self {
|
||||
Self::Configure => Lc::n("Configure the garden"),
|
||||
Self::SeeHarvest => Lc::n("See the harvest report"),
|
||||
}
|
||||
}
|
||||
|
||||
fn group(&self) -> &'static str {
|
||||
"garden"
|
||||
}
|
||||
|
||||
fn group_label(&self) -> Lc {
|
||||
Lc::n("Community garden")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Regístralo con `DeclarePermissions` para que aparezca en la pantalla de roles (lo verás en el
|
||||
ejemplo completo).
|
||||
|
||||
## 3. Deja que el panel construya tus ajustes
|
||||
|
||||
Para una página de ajustes no necesitas ni *handler* ni ruta. Describe los campos con un
|
||||
`SettingsSchema` y declara la página con `AdminPageKind::ConfigForm`. El panel registra la ruta,
|
||||
pinta el formulario con los valores actuales, comprueba que llegan los obligatorios y guarda lo
|
||||
que se envía:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_admin::prelude::*;
|
||||
# #[derive(Clone, Copy, Debug)]
|
||||
# enum GardenPermission { Configure }
|
||||
# impl Permission for GardenPermission {
|
||||
# fn key(&self) -> CowStr { "garden.configure".into() }
|
||||
# }
|
||||
fn garden_settings() -> SettingsSchema {
|
||||
SettingsSchema::new("garden")
|
||||
.with_field(
|
||||
SettingField::text("notice", "Notice for the gardeners")
|
||||
.with_help("Shown on the home page. Leave it empty to hide it."),
|
||||
)
|
||||
.with_field(SettingField::number("plots", "Number of plots").with_required(true))
|
||||
.with_field(SettingField::boolean("open", "Open to new gardeners"))
|
||||
}
|
||||
|
||||
fn declare_pages(bag: &mut PageBag) {
|
||||
bag.add(AdminPage {
|
||||
path: "/admin/config/garden".to_owned(),
|
||||
section: "config".to_owned(),
|
||||
title: Lc::n("Garden"),
|
||||
description: Some(Lc::n("Notice, plots and new gardeners.")),
|
||||
weight: 0,
|
||||
permission: &GardenPermission::Configure,
|
||||
kind: AdminPageKind::ConfigForm(garden_settings()),
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
Los campos pueden ser `text`, `number`, `boolean` o `select` (con sus opciones), y admiten
|
||||
`with_required()`, `with_help()` y `with_default()`.
|
||||
|
||||
Las páginas se agrupan en las secciones del panel: `people` (personas), `structure` (estructura),
|
||||
`config` (configuración), `reports` (informes) y `help` (ayuda). El campo `path` es la ruta de la
|
||||
página, que suele colgar de la de su sección (`/admin/config/...`).
|
||||
|
||||
## 4. Lee los ajustes guardados
|
||||
|
||||
Cada campo se guarda con la clave `<ámbito>.<campo>`: aquí, `garden.notice`, `garden.plots` y
|
||||
`garden.open`. Léelos con `pagetop_admin::settings::get_or()`, con el valor que quieras mientras
|
||||
nadie los haya guardado:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
let notice: String = pagetop_admin::settings::get_or("garden.notice", String::new()).await;
|
||||
let open = pagetop_admin::settings::get_or("garden.open", String::new()).await == "true";
|
||||
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Community garden"))
|
||||
.with_child(Html::with(move |_| {
|
||||
html! {
|
||||
@if !notice.is_empty() {
|
||||
p class="garden-notice" { (notice) }
|
||||
}
|
||||
p { @if open { "We are open to new gardeners." } @else { "No free plots now." } }
|
||||
}
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
El formulario guarda todos los valores **como texto**, también los números y las casillas
|
||||
(`"true"` o `"false"`): conviértelos al leerlos.
|
||||
|
||||
## 5. Añade una página con tu propio contenido
|
||||
|
||||
Cuando la página no es un formulario de ajustes, declárala con `AdminPageKind::View` y registra tú
|
||||
la ruta. El *handler* crea la página con `Page::admin()` y envuelve el contenido en un
|
||||
`AdminFrame`, que añade la ruta de migas, el título y las pestañas y botones del panel:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_admin::prelude::*;
|
||||
# #[derive(Clone, Copy, Debug)]
|
||||
# enum GardenPermission { SeeHarvest }
|
||||
# impl Permission for GardenPermission {
|
||||
# fn key(&self) -> CowStr { "garden.see_harvest".into() }
|
||||
# }
|
||||
fn declare_report(bag: &mut PageBag) {
|
||||
bag.add(AdminPage {
|
||||
path: "/admin/reports/harvest".to_owned(),
|
||||
section: "reports".to_owned(),
|
||||
title: Lc::n("Harvest"),
|
||||
description: Some(Lc::n("Kilos harvested by crop.")),
|
||||
weight: 0,
|
||||
permission: &GardenPermission::SeeHarvest,
|
||||
kind: AdminPageKind::View,
|
||||
});
|
||||
}
|
||||
|
||||
async fn harvest(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
require_permission(&request, &GardenPermission::SeeHarvest)?;
|
||||
|
||||
let rows = [("Tomatoes", 42), ("Lettuces", 18), ("Courgettes", 27)];
|
||||
Page::admin(request)
|
||||
.with_title(Lc::n("Harvest"))
|
||||
.with_child(
|
||||
AdminFrame::new().with_title(Lc::n("Harvest")).with_child(Html::with(move |_| {
|
||||
html! {
|
||||
ul {
|
||||
@for (crop, kilos) in rows {
|
||||
li { (crop) ": " (kilos) " kg" }
|
||||
}
|
||||
}
|
||||
}
|
||||
})),
|
||||
)
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
Declarar la página no protege la ruta: el `require_permission()` del principio sigue haciendo
|
||||
falta, porque cualquiera puede escribir la URL.
|
||||
|
||||
## 6. Crea una sección propia (opcional)
|
||||
|
||||
Si ninguna sección encaja, declara la tuya con `DeclareAdminSections`. Aparece en el panel en
|
||||
cuanto tenga alguna página que el usuario pueda abrir:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_admin::prelude::*;
|
||||
fn declare_sections(bag: &mut SectionBag) {
|
||||
bag.add(AdminSection {
|
||||
key: "garden".to_owned(),
|
||||
path: "/admin/garden".to_owned(),
|
||||
title: Lc::n("Garden"),
|
||||
weight: 25,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
Regístrala junto a las páginas: `actions![DeclareAdminSections::new(declare_sections), ...]`. El
|
||||
peso decide su posición entre las demás (las de serie usan 10, 20, 30...). Con
|
||||
`DeclareAdminTasks` y `DeclareAdminActions` puedes añadir también pestañas y botones a una página.
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_admin::prelude::*;
|
||||
use pagetop_user::PermissionRegistry;
|
||||
use pagetop_user::prelude::*;
|
||||
|
||||
#[derive(Clone, Copy, Debug)]
|
||||
enum GardenPermission {
|
||||
Configure,
|
||||
SeeHarvest,
|
||||
}
|
||||
|
||||
impl Permission for GardenPermission {
|
||||
fn key(&self) -> CowStr {
|
||||
match self {
|
||||
Self::Configure => "garden.configure".into(),
|
||||
Self::SeeHarvest => "garden.see_harvest".into(),
|
||||
}
|
||||
}
|
||||
|
||||
fn label(&self) -> Lc {
|
||||
match self {
|
||||
Self::Configure => Lc::n("Configure the garden"),
|
||||
Self::SeeHarvest => Lc::n("See the harvest report"),
|
||||
}
|
||||
}
|
||||
|
||||
fn group(&self) -> &'static str {
|
||||
"garden"
|
||||
}
|
||||
|
||||
fn group_label(&self) -> Lc {
|
||||
Lc::n("Community garden")
|
||||
}
|
||||
}
|
||||
|
||||
fn declare_permissions(registry: &mut PermissionRegistry) {
|
||||
registry.register(&GardenPermission::Configure);
|
||||
registry.register(&GardenPermission::SeeHarvest);
|
||||
}
|
||||
|
||||
fn garden_settings() -> SettingsSchema {
|
||||
SettingsSchema::new("garden")
|
||||
.with_field(
|
||||
SettingField::text("notice", "Notice for the gardeners")
|
||||
.with_help("Shown on the home page. Leave it empty to hide it."),
|
||||
)
|
||||
.with_field(SettingField::number("plots", "Number of plots").with_required(true))
|
||||
.with_field(SettingField::boolean("open", "Open to new gardeners"))
|
||||
}
|
||||
|
||||
fn declare_pages(bag: &mut PageBag) {
|
||||
bag.add(AdminPage {
|
||||
path: "/admin/config/garden".to_owned(),
|
||||
section: "config".to_owned(),
|
||||
title: Lc::n("Garden"),
|
||||
description: Some(Lc::n("Notice, plots and new gardeners.")),
|
||||
weight: 0,
|
||||
permission: &GardenPermission::Configure,
|
||||
kind: AdminPageKind::ConfigForm(garden_settings()),
|
||||
});
|
||||
bag.add(AdminPage {
|
||||
path: "/admin/reports/harvest".to_owned(),
|
||||
section: "reports".to_owned(),
|
||||
title: Lc::n("Harvest"),
|
||||
description: Some(Lc::n("Kilos harvested by crop.")),
|
||||
weight: 0,
|
||||
permission: &GardenPermission::SeeHarvest,
|
||||
kind: AdminPageKind::View,
|
||||
});
|
||||
}
|
||||
|
||||
struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_user::User]
|
||||
}
|
||||
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![
|
||||
DeclarePermissions::new(declare_permissions),
|
||||
DeclareAdminPages::new(declare_pages),
|
||||
]
|
||||
}
|
||||
|
||||
async fn initialize(&self) -> Result<(), BoxError> {
|
||||
InRegion::Global(&CoreRegions::Header).add(TopBar::new());
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(home))
|
||||
.route("/admin/reports/harvest", web::get(harvest))
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(AutoDefault, Clone, Debug)]
|
||||
struct TopBar;
|
||||
|
||||
#[async_trait]
|
||||
impl Component for TopBar {
|
||||
fn new() -> Self {
|
||||
Self
|
||||
}
|
||||
|
||||
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
|
||||
let brand = Brand::new()
|
||||
.with_title(Lc::n("Community garden"))
|
||||
.with_route(Route::from("/"));
|
||||
Ok(Navbar::brand_left(brand)
|
||||
.with_item(navbar::Item::nav(account_menu(cx)))
|
||||
.render(cx)
|
||||
.await)
|
||||
}
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
let notice: String = pagetop_admin::settings::get_or("garden.notice", String::new()).await;
|
||||
let open = pagetop_admin::settings::get_or("garden.open", String::new()).await == "true";
|
||||
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Community garden"))
|
||||
.with_child(Html::with(move |_| {
|
||||
html! {
|
||||
@if !notice.is_empty() {
|
||||
p class="garden-notice" { (notice) }
|
||||
}
|
||||
p { @if open { "We are open to new gardeners." } @else { "No free plots now." } }
|
||||
}
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn harvest(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
require_permission(&request, &GardenPermission::SeeHarvest)?;
|
||||
|
||||
let rows = [("Tomatoes", 42), ("Lettuces", 18), ("Courgettes", 27)];
|
||||
Page::admin(request)
|
||||
.with_title(Lc::n("Harvest"))
|
||||
.with_child(
|
||||
AdminFrame::new().with_title(Lc::n("Harvest")).with_child(Html::with(move |_| {
|
||||
html! {
|
||||
ul {
|
||||
@for (crop, kilos) in rows {
|
||||
li { (crop) ": " (kilos) " kg" }
|
||||
}
|
||||
}
|
||||
}
|
||||
})),
|
||||
)
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Garden).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
Usa la misma configuración de base de datos y del administrador que en [Añadir usuarios y
|
||||
permisos](users.md#2-configura-la-base-de-datos-y-el-primer-administrador).
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Sin iniciar sesión, <http://localhost:8080/admin/reports/harvest> responde con la página de
|
||||
acceso denegado (403).
|
||||
2. Inicia sesión como `admin` y entra en **Administración** desde el menú de cuenta. El inicio del
|
||||
panel muestra «Garden» en Configuración y «Harvest» en Informes.
|
||||
3. Abre «Garden», escribe un aviso, marca «Open to new gardeners» y guarda. La portada muestra el
|
||||
aviso y «We are open to new gardeners.».
|
||||
4. En la pantalla de roles aparece el grupo «Community garden» con sus dos permisos. Concede «See
|
||||
the harvest report» a otro rol: sus usuarios verán el informe, pero no los ajustes.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Añadir usuarios y permisos](users.md): roles, permisos y el menú de cuenta.
|
||||
- [Extensiones oficiales](../reference/extensions.md#administración): lo que aporta
|
||||
`pagetop-admin`.
|
||||
- [Intervenir con acciones](actions.md): `DeclareAdminPages` y compañía son acciones.
|
||||
105
doc/v0.6/es/src/how-to/assets.md
Normal file
105
doc/v0.6/es/src/how-to/assets.md
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
# Servir recursos estáticos
|
||||
|
||||
**Objetivo:** incluir en el binario las hojas de estilo, *scripts*, fuentes e imágenes de tu
|
||||
aplicación, publicarlos en una ruta y usarlos en las páginas.
|
||||
|
||||
Hojas de estilo, *scripts*, fuentes e imágenes se **incluyen en el binario** al compilar. En
|
||||
producción no hay que copiar ningún directorio: el ejecutable lo lleva todo.
|
||||
|
||||
## 1. Sigue la convención `assets/` -> `static/`
|
||||
|
||||
```text
|
||||
my-app/
|
||||
├── assets/ <- versioned sources (SCSS, JS, images...)
|
||||
├── static/ <- generated when compiling; add it to .gitignore
|
||||
└── build.rs <- turns assets/ into static/ and prepares the bundles
|
||||
```
|
||||
|
||||
Añade `pagetop-build` como dependencia de compilación:
|
||||
|
||||
```toml
|
||||
[build-dependencies]
|
||||
pagetop-build = { git = "https://git.cillero.es/manuelcillero/pagetop" }
|
||||
```
|
||||
|
||||
## 2. Prepara el `build.rs`
|
||||
|
||||
```rust,no_run
|
||||
use pagetop_build::*;
|
||||
|
||||
fn main() -> std::io::Result<()> {
|
||||
// Regenerates static/ only if something changes in assets/.
|
||||
println!("cargo:rerun-if-changed=assets");
|
||||
let _ = std::fs::remove_dir_all("static");
|
||||
|
||||
// Transforms the sources.
|
||||
compile_scss("assets/scss/app.scss", "static/css/app.min.css")?;
|
||||
minify_js("assets/js/app.js", "static/js/app.min.js")?;
|
||||
copy_dir("assets/img", "static/img")?;
|
||||
|
||||
// Bundles static/ to include it in the binary with the name "app".
|
||||
StaticFilesBundle::from_dir("./static", None)
|
||||
.with_name("app")
|
||||
.build()
|
||||
}
|
||||
```
|
||||
|
||||
Funciones disponibles: `compile_scss()`, `minify_js()`, `copy_dir()`, `copy_file()` y
|
||||
`copy_file_replacing()`, que copia sustituyendo textos (útil para corregir referencias al renombrar
|
||||
archivos). Puedes crear varios paquetes, cada uno con su nombre.
|
||||
|
||||
## 3. Sirve los archivos
|
||||
|
||||
En la extensión, publica el paquete con `serve_static_files!` dentro de
|
||||
`configure_static_files()`:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
pub struct MyApp;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for MyApp {
|
||||
fn configure_static_files(&self, router: Router) -> Router {
|
||||
serve_static_files!(router, ["./static", app] => "/static");
|
||||
router
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Con la forma `["./static", app]`, si el directorio existe en disco (durante el desarrollo) los
|
||||
archivos se sirven desde ahí y puedes editarlos sin recompilar; si no existe (en producción), se
|
||||
sirven desde el binario. Con `[app]` se sirven siempre desde el binario.
|
||||
|
||||
Las rutas de `configure_static_files()` no pasan por el *middleware* de las extensiones: servir un
|
||||
archivo no resuelve sesiones ni hace trabajo innecesario. Los archivos se sirven con `ETag`, así
|
||||
que el navegador sólo los descarga de nuevo si cambian.
|
||||
|
||||
## 4. Úsalos en las páginas
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_assets(StyleSheet::from("/static/css/app.min.css").with_version("1.0"))
|
||||
.with_assets(JavaScript::defer("/static/js/app.min.js").with_version("1.0"))
|
||||
.with_child(Html::with(|_| html! { img src="/static/img/logo.svg" alt="Logo"; }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
Si tu extensión es un componente o un tema, añade sus recursos en el `setup()` del componente o
|
||||
en el tema: así se cargan sólo cuando hacen falta.
|
||||
|
||||
## Comprueba
|
||||
|
||||
Pide uno de los archivos directamente (`curl -I http://localhost:8080/static/css/app.min.css`):
|
||||
responde `200` con su `ETag`. Compila en modo *release*, borra `static/` y arranca el binario:
|
||||
sigue sirviéndolo, desde dentro del ejecutable.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Crear un componente](custom-components.md#5-sus-propios-estilos): componentes que traen sus
|
||||
propios estilos.
|
||||
- [Desplegar en producción](deployment.md).
|
||||
202
doc/v0.6/es/src/how-to/components.md
Normal file
202
doc/v0.6/es/src/how-to/components.md
Normal file
|
|
@ -0,0 +1,202 @@
|
|||
# Usar componentes
|
||||
|
||||
**Objetivo:** construir la interfaz con los componentes que trae PageTop: crearlos, configurarlos,
|
||||
anidarlos y ajustar sus clases y atributos sin tocar su código.
|
||||
|
||||
Un **componente** es una pieza de interfaz con su propio HTML (y, si los necesita, sus estilos y
|
||||
*scripts*). Se crea con un constructor, se configura con métodos `with_*()` encadenados y se añade
|
||||
a una página o a otro componente.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_child(
|
||||
Block::new()
|
||||
.with_title(Lc::n("What's new"))
|
||||
.with_child(Html::with(|_| html! { p { "Version 2 is here." } }))
|
||||
.with_child(Button::anchor(Lc::n("Download"), "/downloads")),
|
||||
)
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
Los componentes **no se pintan al crearlos**, sino al renderizar la página. Por eso pueden
|
||||
adaptarse al idioma de cada visitante, al tema activo o al usuario conectado.
|
||||
|
||||
## El catálogo básico
|
||||
|
||||
PageTop trae un conjunto de componentes que funcionan con cualquier tema. La lista completa, con
|
||||
sus constructores, está en el [catálogo de componentes](../reference/components.md).
|
||||
|
||||
| Componente | Para qué sirve |
|
||||
|---|---|
|
||||
| `Html` | Marcado puntual con `html!` |
|
||||
| `Container` | Agrupa componentes en un `<div>`, `<section>`, `<header>`... |
|
||||
| `Block` | Bloque con título y contenido |
|
||||
| `Intro` | Portada de bienvenida con título, eslogan y botón |
|
||||
| `Button` | Botones y enlaces con aspecto de botón |
|
||||
| `Badge` | Etiquetas pequeñas de estado |
|
||||
| `Image` | Imágenes, también *responsive* |
|
||||
| `Brand` | Logotipo y nombre del sitio |
|
||||
| `Breadcrumb` | Migas de pan |
|
||||
| `Messages` | Avisos al usuario |
|
||||
| `Dialog` | Ventanas de diálogo |
|
||||
| `Flex`, `Grid` | [Maquetación](layout.md) |
|
||||
| `Nav`, `Navbar`, `Dropdown` | [Navegación](navigation.md) |
|
||||
| `Form` y sus campos | [Formularios](forms.md) |
|
||||
| `Table`, `Pager` | [Tablas y paginación](tables.md) |
|
||||
| `PoweredBy` | Pie con el crédito «Funciona con PageTop» |
|
||||
|
||||
## Contenedores
|
||||
|
||||
`Container` agrupa varios componentes. Elige la etiqueta con el constructor:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Container {
|
||||
Container::section()
|
||||
.with_id("team")
|
||||
.with_child(Html::with(|_| html! { h2 { "The team" } }))
|
||||
.with_child(Block::new().with_title(Lc::n("Ana")))
|
||||
.with_child(Block::new().with_title(Lc::n("Luke")))
|
||||
# }
|
||||
```
|
||||
|
||||
`Container::new()` genera un `<div>`; también están `header()`, `main()`, `section()`,
|
||||
`article()` y `footer()`.
|
||||
|
||||
## Botones
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Vec<Button> { vec![
|
||||
// A link that looks like a button.
|
||||
Button::anchor(Lc::n("See the catalog"), "/catalog"),
|
||||
// A form submit button, with style and intent.
|
||||
Button::submit(Lc::n("Save"))
|
||||
.with_style(button::Style::Solid(Intent::Success))
|
||||
.with_size(button::Size::Large),
|
||||
// An outline button, disabled.
|
||||
Button::plain(Lc::n("Delete"))
|
||||
.with_style(button::Style::Outline(Intent::Severe))
|
||||
.with_disabled(true),
|
||||
# ] }
|
||||
```
|
||||
|
||||
## Intenciones
|
||||
|
||||
Muchos componentes reciben una `Intent`: el **significado** del color, no el color. El tema decide
|
||||
cómo se ve cada una.
|
||||
|
||||
| `Intent` | Significado |
|
||||
|---|---|
|
||||
| `Primary` | Acción principal |
|
||||
| `Neutral` | Sin énfasis |
|
||||
| `Info` | Información |
|
||||
| `Success` | Éxito o confirmación |
|
||||
| `Warning` | Advertencia |
|
||||
| `Severe` | Error o acción peligrosa |
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Vec<Badge> { vec![
|
||||
Badge::success(Lc::n("Active")),
|
||||
Badge::warning(Lc::n("Pending")),
|
||||
Badge::neutral(Lc::n("Archived")),
|
||||
# ] }
|
||||
```
|
||||
|
||||
## Imágenes
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Image {
|
||||
Image::with(image::Source::responsive("/static/img/cover.jpg"))
|
||||
.with_alternative(Lc::n("View of the harbour at dawn"))
|
||||
# }
|
||||
```
|
||||
|
||||
El origen (`image::Source`) decide cómo se muestra: `plain()` a su tamaño, `responsive()` ajustada
|
||||
al ancho disponible y `thumbnail()` como miniatura.
|
||||
|
||||
## Identificadores, clases y estilos
|
||||
|
||||
Todos los componentes aceptan `with_id()` y `with_prop()`. Con `PropsOp` añades clases, atributos
|
||||
o estilos sin tocar el componente:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Block {
|
||||
Block::new()
|
||||
.with_id("featured")
|
||||
.with_prop(PropsOp::add_classes("block-highlight shadow"))
|
||||
.with_prop(PropsOp::set("data-section", "home"))
|
||||
.with_prop(PropsOp::add_style("border-radius", "8px"))
|
||||
# }
|
||||
```
|
||||
|
||||
Para márgenes y rellenos hay tipos propios, `Margin` y `Padding`, con unidades tipadas:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Block {
|
||||
Block::new()
|
||||
.with_prop(Margin::new().with_bottom(UnitValue::RelRem(2.0)))
|
||||
.with_prop(Padding::new().with_all(UnitValue::Px(16)))
|
||||
# }
|
||||
```
|
||||
|
||||
## Mensajes al usuario
|
||||
|
||||
`Page` acumula avisos en su contexto, y la región de contenido empieza siempre por un componente
|
||||
`Messages` que los muestra. Basta con añadirlos:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
async fn saved(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
let mut page = Page::new(request);
|
||||
page.context()
|
||||
.push_message(MessageLevel::Info, Lc::n("Your changes have been saved."));
|
||||
page.render().await
|
||||
}
|
||||
```
|
||||
|
||||
Ese `Messages` se renderiza el último, cuando ya está hecho el resto de la página, así que recoge
|
||||
también los avisos que añadan los componentes al renderizarse, aunque se muestre al principio. Cada
|
||||
aviso aparece una sola vez: añade tu propio `Messages::new()` sólo para mostrarlos en otro lugar,
|
||||
por ejemplo justo antes de un formulario, o en un fragmento de HTMX, que no tiene página.
|
||||
|
||||
Para avisar en la página a la que rediriges, añade el mensaje a la respuesta con `with_message()`
|
||||
(ver [Crear y procesar formularios](forms.md#3-recibe-y-valida-los-datos)).
|
||||
|
||||
## Una portada en un minuto
|
||||
|
||||
`Intro` monta una página de presentación con un solo componente:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
async fn landing(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_child(
|
||||
Intro::custom()
|
||||
.with_title(Lc::n("Urban Garden"))
|
||||
.with_slogan(Lc::n("Grow your city"))
|
||||
.with_button(Some((Lc::n("Start here"), Route::from("/guide"))))
|
||||
.with_child(
|
||||
Block::new()
|
||||
.with_title(Lc::n("What is it?"))
|
||||
.with_child(Html::with(|_| html! { p { "A network of community gardens." } })),
|
||||
),
|
||||
)
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Crear un componente](custom-components.md), cuando ninguno encaja.
|
||||
- [Maquetar con Flex y Grid](layout.md).
|
||||
- [Catálogo de componentes](../reference/components.md).
|
||||
164
doc/v0.6/es/src/how-to/configuration.md
Normal file
164
doc/v0.6/es/src/how-to/configuration.md
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
# Configurar la aplicación
|
||||
|
||||
**Objetivo:** ajustar la aplicación con archivos TOML, distintos por entorno y sin recompilar, y
|
||||
dar a tu extensión sus propios ajustes, validados al arrancar.
|
||||
|
||||
La configuración vive en archivos [TOML](https://toml.io) dentro del directorio `config/`, junto
|
||||
al `Cargo.toml`. Cambiar un puerto o un idioma no requiere recompilar.
|
||||
|
||||
## 1. Entiende la cascada de archivos
|
||||
|
||||
PageTop lee estos archivos, todos opcionales, en este orden. Cada uno sobrescribe a los anteriores
|
||||
**sólo** en las claves que define:
|
||||
|
||||
| Archivo | Para qué |
|
||||
|---|---|
|
||||
| `config/common.toml` | Ajustes comunes a todos los entornos |
|
||||
| `config/{mode}.toml` | Ajustes del modo de ejecución |
|
||||
| `config/local.{mode}.toml` | Ajustes locales de ese modo (no se versiona) |
|
||||
| `config/local.toml` | Ajustes locales para cualquier modo (no se versiona) |
|
||||
|
||||
El modo lo da la variable de entorno `PAGETOP_RUN_MODE` (`default` si no se define):
|
||||
|
||||
```sh
|
||||
PAGETOP_RUN_MODE=production ./my-app # reads common.toml, production.toml, ...
|
||||
```
|
||||
|
||||
`CONFIG_DIR` cambia el directorio `config/`. Las contraseñas y demás secretos van en un
|
||||
`local.toml` que no se sube al repositorio, o en variables de entorno: cualquier clave se
|
||||
sobrescribe con `PAGETOP_<SECCIÓN>__<CLAVE>`, con cada nivel separado por dos guiones bajos.
|
||||
|
||||
```sh
|
||||
PAGETOP_DATABASE__DB_PASS=secret ./my-app # db_pass of [database]
|
||||
```
|
||||
|
||||
## 2. Ajusta PageTop
|
||||
|
||||
Un `config/common.toml` típico:
|
||||
|
||||
```toml
|
||||
[app]
|
||||
name = "Urban Garden"
|
||||
theme = "Bootsier"
|
||||
language = "es-ES"
|
||||
timezone = "Europe/Madrid"
|
||||
|
||||
[server]
|
||||
bind_address = "0.0.0.0"
|
||||
bind_port = 8080
|
||||
|
||||
[log]
|
||||
tracing = "Info"
|
||||
rolling = "Daily"
|
||||
```
|
||||
|
||||
| Sección | Claves principales |
|
||||
|---|---|
|
||||
| `[app]` | `name`, `theme` (por defecto `"Basic"`), `language`, `lang_negotiation`, `timezone`, `startup_banner` |
|
||||
| `[server]` | `bind_address` (por defecto `"localhost"`), `bind_port` (por defecto `8080`) |
|
||||
| `[log]` | `enabled`, `tracing`, `rolling`, `path`, `prefix`, `format` |
|
||||
| `[dev]` | `pagetop_static_dir`, para servir los recursos de PageTop desde disco |
|
||||
|
||||
Todas las opciones, con su tipo y su valor por defecto, están en [Opciones de
|
||||
configuración](../reference/configuration.md).
|
||||
|
||||
## 3. Léelos desde el código
|
||||
|
||||
Los ajustes de PageTop se leen en `global::SETTINGS`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() {
|
||||
let name = &global::SETTINGS.app.name;
|
||||
let port = global::SETTINGS.server.bind_port;
|
||||
# }
|
||||
```
|
||||
|
||||
## 4. Errores que no pasan desapercibidos
|
||||
|
||||
Una **clave desconocida** (típicamente, una errata) o un **valor no válido** impiden arrancar la
|
||||
aplicación, con un mensaje que lo localiza: el archivo y la línea si el TOML está mal escrito, o la
|
||||
sección y la clave si el valor no es válido. Una sección que no corresponde a
|
||||
ninguna extensión se ignora, con un aviso al arrancar.
|
||||
|
||||
## 5. Ajustes de tu extensión
|
||||
|
||||
Cada extensión declara sus ajustes en una estructura con `#[settings]`, ligada a una **sección
|
||||
propia** del archivo. Los valores por defecto van en los campos:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
/// Settings of the `[blog]` section.
|
||||
pub static SETTINGS: LazySettings<BlogSettings> = LazySettings::new();
|
||||
|
||||
/// The **`[blog]`** section of the configuration.
|
||||
#[settings(section = "blog")]
|
||||
pub struct BlogSettings {
|
||||
/// Title of the blog.
|
||||
#[default = "My blog"]
|
||||
pub title: String,
|
||||
/// Posts per page.
|
||||
#[default = 10]
|
||||
pub page_size: u32,
|
||||
/// Optional footer text (no default value: `None`).
|
||||
pub footer: Option<String>,
|
||||
/// Comments, in the `[blog.comments]` subsection.
|
||||
pub comments: CommentsSettings,
|
||||
}
|
||||
|
||||
/// The **`[blog.comments]`** subsection.
|
||||
#[settings]
|
||||
pub struct CommentsSettings {
|
||||
/// Whether comments are allowed.
|
||||
#[default = true]
|
||||
pub enabled: bool,
|
||||
}
|
||||
```
|
||||
|
||||
La extensión los devuelve en `settings()` para que se carguen (y se validen) al arrancar:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# pub static SETTINGS: LazySettings<BlogSettings> = LazySettings::new();
|
||||
# #[settings(section = "blog")]
|
||||
# pub struct BlogSettings {
|
||||
# #[default = 10]
|
||||
# pub page_size: u32,
|
||||
# }
|
||||
pub struct Blog;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Blog {
|
||||
fn settings(&self) -> Option<&'static dyn LoadSettings> {
|
||||
Some(&SETTINGS)
|
||||
}
|
||||
}
|
||||
|
||||
fn posts_per_page() -> u32 {
|
||||
SETTINGS.page_size
|
||||
}
|
||||
```
|
||||
|
||||
Y en `config/common.toml`:
|
||||
|
||||
```toml
|
||||
[blog]
|
||||
title = "Garden diary"
|
||||
|
||||
[blog.comments]
|
||||
enabled = false
|
||||
```
|
||||
|
||||
Los ajustes son de **sólo lectura** mientras la aplicación está en marcha.
|
||||
|
||||
## Comprueba
|
||||
|
||||
Escribe mal una clave en `config/common.toml` (`bind_prot = 9000`) y arranca: la aplicación se
|
||||
detiene y señala la clave. Corrígela y arranca con `PAGETOP_RUN_MODE=production`: se leen además
|
||||
`production.toml` y `local.production.toml`, si existen.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Opciones de configuración](../reference/configuration.md): la referencia completa.
|
||||
- [Desplegar en producción](deployment.md): la configuración en el servidor.
|
||||
339
doc/v0.6/es/src/how-to/cron.md
Normal file
339
doc/v0.6/es/src/how-to/cron.md
Normal file
|
|
@ -0,0 +1,339 @@
|
|||
# Programar tareas periódicas
|
||||
|
||||
**Objetivo:** ejecutar código en segundo plano mientras la aplicación está en marcha, según un
|
||||
calendario (cada noche a las 4:30, cada lunes) o a intervalos (cada diez minutos), y dejar que
|
||||
quien administra la aplicación lo cambie o lo desactive sin recompilar.
|
||||
|
||||
Lo aporta la extensión `pagetop-cron`. Cada extensión **declara** sus trabajos con una acción, y el
|
||||
planificador los ejecuta cuando toca. El planificador sólo se pone en marcha con
|
||||
`Application::run()`: en las pruebas no se ejecuta nada por sí solo, y cada prueba ejecuta el
|
||||
trabajo que quiere cuando quiere.
|
||||
|
||||
## 1. Añade la dependencia
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
pagetop-cron = { git = "https://git.cillero.es/manuelcillero/pagetop" }
|
||||
```
|
||||
|
||||
Y declara `pagetop_cron::Cron` en `dependencies()` de la extensión que aporta los trabajos:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
pub struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_cron::Cron]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Escribe el trabajo
|
||||
|
||||
Un trabajo es una función asíncrona que recibe un `JobContext` y devuelve un `JobResult`. Lee los
|
||||
ajustes y los servicios de la aplicación igual que un *handler* (ve [Compartir un servicio entre
|
||||
rutas](services.md)), y con `?` propaga cualquier error, que queda registrado en las trazas:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_cron::prelude::*;
|
||||
async fn water_plots(cx: JobContext) -> JobResult {
|
||||
let plan = std::fs::read_to_string("watering-plan.txt")?;
|
||||
trace::info!("Watering {} plots ({:?})", plan.lines().count(), cx.trigger());
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Si el trabajo devuelve un error o provoca un `panic!`, la aplicación sigue en marcha y el trabajo
|
||||
vuelve a ejecutarse cuando le toque.
|
||||
|
||||
## 3. Declara cuándo se ejecuta
|
||||
|
||||
Los trabajos se declaran con la acción `DeclareCronJobs`. Cada uno tiene una **clave** única, que
|
||||
conviene empezar por el nombre de la extensión, y una programación (`Schedule`):
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_cron::prelude::*;
|
||||
# async fn water_plots(_cx: JobContext) -> JobResult { Ok(()) }
|
||||
fn declare_jobs(jobs: &mut CronJobs) {
|
||||
jobs.add(
|
||||
Job::new("garden.water", Schedule::cron("30 6 * * *"), water_plots)
|
||||
.with_title(Lc::n("Water the plots")),
|
||||
);
|
||||
}
|
||||
|
||||
pub struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_cron::Cron]
|
||||
}
|
||||
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![DeclareCronJobs::new(declare_jobs)]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Hay tres formas de programarlo:
|
||||
|
||||
| Programación | Se ejecuta... |
|
||||
|---|---|
|
||||
| `Schedule::cron("30 6 * * *")` | Según una expresión cron: cada día a las 6:30 |
|
||||
| `Schedule::fixed_rate(Duration::minutes(10))` | Cada 10 minutos desde que **empieza** la ejecución anterior |
|
||||
| `Schedule::fixed_delay(Duration::seconds(30))` | 30 segundos después de que **termina** la ejecución anterior |
|
||||
|
||||
Las expresiones cron tienen los cinco campos clásicos (minuto, hora, día del mes, mes y día de la
|
||||
semana), con un sexto campo opcional al principio para los segundos. Algunos ejemplos:
|
||||
|
||||
| Expresión | Se ejecuta... |
|
||||
|---|---|
|
||||
| `*/10 * * * *` | Cada diez minutos |
|
||||
| `0 8-18 * * MON-FRI` | A cada hora en punto, de 8 a 18, de lunes a viernes |
|
||||
| `0 0 L * *` | A medianoche del último día de cada mes |
|
||||
| `0 9 * * MON#1` | A las 9:00 del primer lunes de cada mes |
|
||||
| `*/30 * * * * *` | Cada treinta segundos |
|
||||
| `@daily`, `@hourly`... | Al principio de cada día, de cada hora... |
|
||||
|
||||
Se interpretan en la zona horaria de la aplicación (`[app] timezone`) y respetan los cambios de
|
||||
hora: una ejecución en una hora que no existe se hace al empezar la siguiente, y una en una hora
|
||||
que se repite, una sola vez. La sintaxis completa está en la documentación de `Schedule`.
|
||||
|
||||
Para procesar algo pendiente (una cola, una lista de avisos), `fixed_delay()` suele ser la mejor
|
||||
opción: dos ejecuciones nunca coinciden, y cada una empieza con lo que dejó la anterior.
|
||||
|
||||
## 4. Ajusta cómo se ejecuta
|
||||
|
||||
`Job` admite además:
|
||||
|
||||
| Método | Para qué |
|
||||
|---|---|
|
||||
| `with_timeout(Duration::minutes(5))` | Cancela la ejecución si dura más |
|
||||
| `with_overlap(Overlap::Allow)` | Ejecuta aunque siga en curso la anterior; por defecto se omite (`Overlap::Skip`) |
|
||||
| `with_run_on_start()` | Ejecuta también al arrancar, sin esperar a la primera hora programada |
|
||||
| `with_timezone(Tz::Europe__Madrid)` | Interpreta su expresión cron en otra zona horaria |
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_cron::prelude::*;
|
||||
# async fn check_sensors(_cx: JobContext) -> JobResult { Ok(()) }
|
||||
# fn f() -> Job {
|
||||
Job::new("garden.sensors", Schedule::fixed_delay(Duration::seconds(30)), check_sensors)
|
||||
.with_timeout(Duration::seconds(20))
|
||||
.with_run_on_start()
|
||||
# }
|
||||
```
|
||||
|
||||
La función también puede ser un cierre, útil para trabajos cortos:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_cron::prelude::*;
|
||||
# fn f() -> Job {
|
||||
Job::new("garden.heartbeat", Schedule::fixed_rate(Duration::minutes(1)), |cx| async move {
|
||||
trace::debug!("Still alive ({})", cx.key());
|
||||
Ok(())
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
## 5. Cámbialo desde la configuración
|
||||
|
||||
Quien administra la aplicación puede cambiar cada trabajo por su clave, sin tocar el código, en la
|
||||
subsección `[cron.jobs."clave"]`. La clave va entre comillas porque lleva un punto:
|
||||
|
||||
```toml
|
||||
[cron.jobs."garden.water"]
|
||||
schedule = "0 7 * * *" # Water at 7:00 instead.
|
||||
timeout_secs = 600 # At most 10 minutes (0 = no limit).
|
||||
|
||||
[cron.jobs."garden.heartbeat"]
|
||||
enabled = false # Never runs on its own.
|
||||
```
|
||||
|
||||
`schedule` admite una expresión cron y también `"@every 10m"` (como `fixed_rate()`) y
|
||||
`"@delay 30s"` (como `fixed_delay()`). Si una programación no es válida, la aplicación no arranca e
|
||||
indica el trabajo; una clave que no corresponde a ningún trabajo sólo produce un aviso en las
|
||||
trazas.
|
||||
|
||||
## 6. Con varias instancias, elige el modo
|
||||
|
||||
Por defecto (`mode = "internal"`) cada instancia de la aplicación ejecuta todos los trabajos. Si
|
||||
despliegas varias (por ejemplo, detrás de un balanceador), cada trabajo se ejecutaría una vez por
|
||||
instancia. Tienes dos opciones:
|
||||
|
||||
- **Uno solo ejecuta los trabajos:** deja `"internal"` en una instancia y pon `"off"` en las demás.
|
||||
- **Un programa externo marca el ritmo:** pon `"external"` en todas y programa una sola llamada
|
||||
cada minuto. Cada llamada llega a una instancia, que ejecuta lo programado en el último minuto:
|
||||
|
||||
```toml
|
||||
[cron]
|
||||
mode = "external"
|
||||
trigger_token = "a-long-and-secret-token" # Better in config/local.toml.
|
||||
```
|
||||
|
||||
```text
|
||||
# System crontab: checks the jobs every minute. The file holds the line
|
||||
# "Authorization: Bearer a-long-and-secret-token".
|
||||
* * * * * curl -fsS -X POST -H @/etc/garden/cron-header https://garden.example.com/cron > /dev/null
|
||||
```
|
||||
|
||||
La clave viaja en la cabecera `Authorization` y no en la ruta, que suelen registrar los *proxies*;
|
||||
necesita al menos 16 letras, dígitos, `-` o `_`. Sin la clave correcta, la ruta responde `404`. La
|
||||
llamada responde `200 OK` cuando terminan los trabajos, con una línea por trabajo y su resultado,
|
||||
así que el programa externo debe esperar más de lo que tarde el más largo.
|
||||
|
||||
Como ninguna instancia recuerda lo que hicieron las demás, el programa externo debe llamar una vez,
|
||||
y sólo una, cada minuto: si falta una llamada se pierden sus ejecuciones, y si sobra, pueden
|
||||
repetirse. Para llamar con otra frecuencia, indícala en `trigger_interval_secs`. En este modo, un
|
||||
trabajo no se ejecuta más a menudo que las llamadas.
|
||||
|
||||
Una llamada de más suele ser un reintento tras un error de red, que puede llegar a otra instancia.
|
||||
Desactiva los reintentos del programa externo (p. ej. `backoffLimit: 0` en un *CronJob* de
|
||||
Kubernetes) y, si un trabajo no debe repetirse nunca, haz que lo compruebe él mismo en la base de
|
||||
datos antes de hacer nada.
|
||||
|
||||
Con `"off"`, los trabajos sólo se ejecutan si alguien lo pide con `pagetop_cron::run_now()`.
|
||||
|
||||
## 7. Termina a tiempo al detener la aplicación
|
||||
|
||||
Al detener la aplicación (Ctrl+C o `SIGTERM`), el planificador deja de lanzar ejecuciones y espera
|
||||
hasta `shutdown_timeout_secs` (30 segundos por defecto) a que terminen las que están en curso. Un
|
||||
trabajo largo puede preguntar por `is_stopping()` y dejar su trabajo en un punto seguro:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_cron::prelude::*;
|
||||
# async fn send_reminder(_n: usize) {}
|
||||
async fn send_reminders(cx: JobContext) -> JobResult {
|
||||
for n in 0..500 {
|
||||
if cx.is_stopping() {
|
||||
trace::info!("Stopping at reminder {n}; the rest go in the next run");
|
||||
break;
|
||||
}
|
||||
send_reminder(n).await;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
Riega el huerto según su programación y muestra en la portada cuántas veces se ha regado y cuándo
|
||||
fue la última, a partir del estado del trabajo (`pagetop_cron::job()`):
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_cron::prelude::*;
|
||||
|
||||
async fn water_plots(cx: JobContext) -> JobResult {
|
||||
trace::info!("Watering the plots ({:?})", cx.trigger());
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn declare_jobs(jobs: &mut CronJobs) {
|
||||
jobs.add(
|
||||
Job::new("garden.water", Schedule::cron("30 6 * * *"), water_plots)
|
||||
.with_title(Lc::n("Water the plots"))
|
||||
.with_timeout(Duration::minutes(5)),
|
||||
);
|
||||
}
|
||||
|
||||
struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_cron::Cron]
|
||||
}
|
||||
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![DeclareCronJobs::new(declare_jobs)]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router.route("/", web::get(home))
|
||||
}
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
let status = pagetop_cron::job("garden.water");
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Garden"))
|
||||
.with_child(Html::with(move |_| match &status {
|
||||
Some(status) => html! {
|
||||
p { "Watered " (status.runs()) " times." }
|
||||
@if let Some(last) = status.last_run() {
|
||||
p { "Last time: " (last.started_at().format("%H:%M:%S UTC")) "." }
|
||||
}
|
||||
@if let Some(next) = status.next_run() {
|
||||
p { "Next time: " (next.format("%Y-%m-%d %H:%M UTC")) "." }
|
||||
}
|
||||
},
|
||||
None => html! { p { "No watering job." } },
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Garden).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
Para no esperar a las 6:30, programa el riego cada diez segundos en `config/local.toml`:
|
||||
|
||||
```toml
|
||||
[cron.jobs."garden.water"]
|
||||
schedule = "@every 10s"
|
||||
```
|
||||
|
||||
Arranca con `cargo run`: el terminal anuncia `Cron scheduler started with 1 of 1 jobs` y, cada diez
|
||||
segundos, `Watering the plots (Schedule)`. Recarga `/` y verás crecer el número de riegos.
|
||||
|
||||
En las pruebas el planificador no arranca: ejecuta el trabajo con `run_now()`, que espera a que
|
||||
termine y devuelve cómo fue:
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_cron::prelude::*;
|
||||
# async fn water_plots(_cx: JobContext) -> JobResult { Ok(()) }
|
||||
# fn declare_jobs(jobs: &mut CronJobs) {
|
||||
# jobs.add(Job::new("garden.water", Schedule::cron("30 6 * * *"), water_plots));
|
||||
# }
|
||||
# struct Garden;
|
||||
# #[async_trait]
|
||||
# impl Extension for Garden {
|
||||
# fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
# vec![&pagetop_cron::Cron]
|
||||
# }
|
||||
# fn actions(&self) -> Vec<ActionBox> {
|
||||
# actions![DeclareCronJobs::new(declare_jobs)]
|
||||
# }
|
||||
# }
|
||||
#[pagetop::test]
|
||||
async fn watering_succeeds() {
|
||||
Application::prepare(&Garden).await;
|
||||
|
||||
let run = pagetop_cron::run_now("garden.water").await.unwrap();
|
||||
assert!(run.outcome().is_success(), "{}", run.outcome());
|
||||
assert_eq!(pagetop_cron::job("garden.water").unwrap().runs(), 1);
|
||||
}
|
||||
```
|
||||
|
||||
Para vigilar todos los trabajos (registrar sus ejecuciones, avisar cuando uno falla), registra la
|
||||
acción `AfterJobRun`, que recibe el informe de cada ejecución terminada.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Opciones de configuración](../reference/configuration.md#cron): todas las claves de `[cron]`.
|
||||
- [Compartir un servicio entre rutas](services.md): los servicios que usan los trabajos.
|
||||
- [Desplegar en producción](deployment.md): la aplicación como servicio, que se detiene de forma
|
||||
ordenada.
|
||||
240
doc/v0.6/es/src/how-to/custom-components.md
Normal file
240
doc/v0.6/es/src/how-to/custom-components.md
Normal file
|
|
@ -0,0 +1,240 @@
|
|||
# Crear un componente
|
||||
|
||||
**Objetivo:** convertir un fragmento de interfaz que se repite en un componente propio: con sus
|
||||
datos, sus métodos `with_*()`, su HTML, sus hijos y sus estilos.
|
||||
|
||||
Antes de crear uno, mira el [catálogo de componentes](../reference/components.md): quizá ya existe.
|
||||
|
||||
## 1. El mínimo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
#[derive(AutoDefault, Clone, Debug)]
|
||||
pub struct Notice;
|
||||
|
||||
#[async_trait]
|
||||
impl Component for Notice {
|
||||
fn new() -> Self {
|
||||
Self
|
||||
}
|
||||
|
||||
async fn prepare(&self, _cx: &mut Context) -> Result<Markup, ComponentError> {
|
||||
Ok(html! { p class="notice" { "Scheduled maintenance on Sunday." } })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Tres requisitos:
|
||||
|
||||
- **`new()`** crea la instancia; lo habitual es devolver `Self::default()`.
|
||||
- **`prepare()`** devuelve el HTML. Es `async`, así que puede consultar una base de datos o un
|
||||
servicio externo.
|
||||
- **`Clone`** es obligatorio, aunque el compilador no lo exija directamente: sin él, el
|
||||
componente no podría clonarse para cada página.
|
||||
|
||||
Ya puedes usarlo como cualquier otro: `.with_child(Notice::new())`.
|
||||
|
||||
## 2. Datos y métodos `with_*()`
|
||||
|
||||
Lo normal es que un componente tenga datos. La receta de PageTop:
|
||||
|
||||
- Campos **privados**, con `Getters` para leerlos.
|
||||
- `AutoDefault` para los valores por defecto.
|
||||
- Métodos `with_*()` para configurarlo, en un bloque `impl` marcado con `#[builder_impl]`.
|
||||
- Los textos como `Lc`, para que se traduzcan al renderizar.
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
#[derive(AutoDefault, Clone, Debug, Getters)]
|
||||
pub struct Card {
|
||||
/// Returns the title of the card.
|
||||
title: Lc,
|
||||
/// Returns the text of the card.
|
||||
text: Lc,
|
||||
/// Returns the link target, if any.
|
||||
link: Option<Route>,
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Component for Card {
|
||||
fn new() -> Self {
|
||||
Self::default()
|
||||
}
|
||||
|
||||
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
|
||||
Ok(html! {
|
||||
div class="card" {
|
||||
h3 class="card-title" { (self.title().using(cx)) }
|
||||
p class="card-text" { (self.text().using(cx)) }
|
||||
@if let Some(link) = self.link() {
|
||||
a href=(link.resolve(cx)) { "Read more" }
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[builder_impl]
|
||||
impl Card {
|
||||
/// Sets the title.
|
||||
pub fn with_title(mut self, title: Lc) -> Self {
|
||||
self.title = title;
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the text.
|
||||
pub fn with_text(mut self, text: Lc) -> Self {
|
||||
self.text = text;
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the link target.
|
||||
pub fn with_link(mut self, link: impl Into<Option<Route>>) -> Self {
|
||||
self.link = link.into();
|
||||
self
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Y se usa así:
|
||||
|
||||
```rust,ignore
|
||||
Card::new()
|
||||
.with_title(Lc::n("Rust"))
|
||||
.with_text(Lc::n("Fast, reliable and productive."))
|
||||
.with_link(Route::from("/rust"))
|
||||
```
|
||||
|
||||
`#[builder_impl]` genera, junto a cada `with_*()`, un método `alter_*()` que modifica la instancia
|
||||
por referencia (`&mut self`). Lo agradecerás cuando un tema o una acción quieran cambiar el
|
||||
componente. Para un método suelto, fuera de un bloque así, existe `#[builder_fn]`.
|
||||
|
||||
## 3. Prepara y pinta
|
||||
|
||||
Cuando una página se renderiza, cada componente pasa por estos pasos, siempre en este orden:
|
||||
|
||||
1. **`is_renderable(cx)`**: ¿se pinta? Si devuelve `false`, el componente desaparece.
|
||||
2. **`setup(&mut self, cx)`**: ajusta su estado antes de pintarse. Es síncrono.
|
||||
3. Las extensiones pueden intervenir con la acción `BeforeRender`.
|
||||
4. El **tema** puede ajustarlo o pintarlo a su manera; si no lo hace, se llama a
|
||||
**`prepare(&self, cx)`**.
|
||||
5. Las extensiones pueden reaccionar (`AfterRender`) o retocar el HTML final
|
||||
(`TransformMarkup`).
|
||||
|
||||
Un ejemplo con los tres métodos propios:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
#[derive(AutoDefault, Clone, Debug, Getters)]
|
||||
pub struct Counter {
|
||||
/// Returns the number of notices.
|
||||
#[getters(copy)]
|
||||
notices: u32,
|
||||
/// Returns the computed CSS classes.
|
||||
classes: String,
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Component for Counter {
|
||||
fn new() -> Self {
|
||||
Self::default()
|
||||
}
|
||||
|
||||
// Nothing is rendered without notices.
|
||||
fn is_renderable(&self, _cx: &Context) -> bool {
|
||||
self.notices() > 0
|
||||
}
|
||||
|
||||
// Computes the classes from the state, before rendering.
|
||||
fn setup(&mut self, _cx: &mut Context) {
|
||||
self.classes = if self.notices > 9 { "counter counter-full" } else { "counter" }.into();
|
||||
}
|
||||
|
||||
async fn prepare(&self, _cx: &mut Context) -> Result<Markup, ComponentError> {
|
||||
Ok(html! { span class=(self.classes()) { (self.notices()) } })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
La regla de oro: **`setup()` prepara, `prepare()` pinta**. Las consultas a la base de datos y
|
||||
cualquier operación de entrada/salida van en `prepare()`, que es el único paso asíncrono.
|
||||
|
||||
## 4. Componentes que contienen componentes
|
||||
|
||||
Para aceptar hijos, guarda un `Children` y renderízalo dentro de `prepare()`:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
#[derive(AutoDefault, Clone, Debug, Getters)]
|
||||
pub struct Panel {
|
||||
/// Returns the child components.
|
||||
children: Children,
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Component for Panel {
|
||||
fn new() -> Self {
|
||||
Self::default()
|
||||
}
|
||||
|
||||
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
|
||||
Ok(html! {
|
||||
div class="panel" { (self.children().render(cx).await) }
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[builder_impl]
|
||||
impl Panel {
|
||||
/// Adds a child component.
|
||||
pub fn with_child(mut self, op: impl Into<ChildOp>) -> Self {
|
||||
self.children.alter_child(op.into());
|
||||
self
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Consejo:** nunca guardes `Markup` ya generado en un campo. Guarda el dato en bruto (`Lc`,
|
||||
> otro componente...) y conviértelo en HTML en `prepare()`. Así el componente se adapta al idioma
|
||||
> y al tema de cada petición.
|
||||
|
||||
## 5. Sus propios estilos
|
||||
|
||||
Un componente puede traer su hoja de estilos o su *script*. Los añade al contexto al renderizarse,
|
||||
así que sólo se cargan en las páginas que lo usan, y una sola vez aunque aparezca muchas veces:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# #[derive(AutoDefault, Clone, Debug)]
|
||||
# pub struct Card;
|
||||
#[async_trait]
|
||||
impl Component for Card {
|
||||
fn new() -> Self {
|
||||
Self::default()
|
||||
}
|
||||
|
||||
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
|
||||
cx.alter_assets(StyleSheet::from("/static/css/card.css").with_version("1.0"));
|
||||
Ok(html! { div class="card" { "..." } })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Cómo publicar ese archivo se explica en [Servir recursos estáticos](assets.md). Usa clases propias
|
||||
con el prefijo del componente (`card-title`, `card-text`...) para no chocar con las del tema.
|
||||
|
||||
## Comprueba
|
||||
|
||||
Usa el componente en una página y renderízala: si te falta `Clone` o un método obligatorio, no
|
||||
compila. Para comprobar su HTML sin servidor, mira [Probar rutas y
|
||||
componentes](testing.md#3-prueba-un-componente-suelto).
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Componentes, temas y renderizado](../explanation/rendering.md): el ciclo completo, con las
|
||||
acciones y el tema.
|
||||
- [Intervenir con acciones](actions.md): cómo otra extensión puede retocar tu componente.
|
||||
813
doc/v0.6/es/src/how-to/database.md
Normal file
813
doc/v0.6/es/src/how-to/database.md
Normal file
|
|
@ -0,0 +1,813 @@
|
|||
# Conectar una base de datos
|
||||
|
||||
**Objetivo:** conectar la aplicación a PostgreSQL, MySQL o SQLite con `pagetop-seaorm`, mantener el
|
||||
esquema con migraciones, consultar los datos con entidades tipadas, relacionar tablas y escribir
|
||||
SQL cuando haga falta.
|
||||
|
||||
El tutorial [Guarda las tareas en una base de datos](../tutorials/database.md) recorre un caso
|
||||
completo paso a paso. Esta guía reúne lo que necesitarás después.
|
||||
|
||||
## 1. Elige el motor
|
||||
|
||||
En una **aplicación**, activa el motor con una *feature* de `pagetop-seaorm`. Declararlas como
|
||||
*features* propias te permite cambiar de motor al compilar:
|
||||
|
||||
```toml
|
||||
[features]
|
||||
default = ["postgres"]
|
||||
postgres = ["pagetop-seaorm/postgres"]
|
||||
mysql = ["pagetop-seaorm/mysql"]
|
||||
sqlite = ["pagetop-seaorm/sqlite"]
|
||||
|
||||
[dependencies]
|
||||
pagetop-seaorm = { git = "https://git.cillero.es/manuelcillero/pagetop" }
|
||||
```
|
||||
|
||||
En una **extensión**, declara la dependencia sin *features*: el motor lo elige la aplicación que la
|
||||
use, y Cargo lo activa para todo el árbol de dependencias.
|
||||
|
||||
## 2. Configura la conexión
|
||||
|
||||
La sección `[database]` describe la conexión. Lo que cambia entre motores:
|
||||
|
||||
```toml
|
||||
# PostgreSQL (port 5432 by default)
|
||||
[database]
|
||||
db_type = "postgres"
|
||||
db_name = "garden"
|
||||
db_user = "garden"
|
||||
db_host = "localhost"
|
||||
```
|
||||
|
||||
```toml
|
||||
# MySQL or MariaDB (port 3306 by default)
|
||||
[database]
|
||||
db_type = "mysql"
|
||||
db_name = "garden"
|
||||
db_user = "garden"
|
||||
db_host = "localhost"
|
||||
```
|
||||
|
||||
```toml
|
||||
# SQLite: db_name is the file; mode=rwc creates it if it does not exist
|
||||
[database]
|
||||
db_type = "sqlite"
|
||||
db_name = "garden.db?mode=rwc"
|
||||
```
|
||||
|
||||
La contraseña, `db_pass`, va en `config/local.toml`, que no se sube al repositorio. `db_port` fija
|
||||
otro puerto y `max_pool_size` el número máximo de conexiones simultáneas (5 por defecto).
|
||||
|
||||
Declara la extensión como dependencia de la tuya. Al arrancar, abre el *pool* de conexiones antes
|
||||
de inicializar tu extensión; si no puede conectar, la aplicación no arranca y explica por qué.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
pub struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_seaorm::SeaORM]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Escribe las migraciones
|
||||
|
||||
Cada migración es un módulo dentro de `migration/`, con un nombre que empieza por la fecha para que
|
||||
el orden sea el cronológico:
|
||||
|
||||
```text
|
||||
src/
|
||||
├── lib.rs
|
||||
└── migration/
|
||||
├── m20261015_000001_create_plots.rs
|
||||
└── m20261101_000002_add_plot_notes.rs
|
||||
```
|
||||
|
||||
Una crea la tabla y un índice:
|
||||
|
||||
```rust,no_run
|
||||
// src/migration/m20261015_000001_create_plots.rs
|
||||
use pagetop_seaorm::migration::*;
|
||||
|
||||
pub struct Migration;
|
||||
|
||||
#[pagetop::async_trait]
|
||||
impl MigrationTrait for Migration {
|
||||
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
|
||||
manager
|
||||
.create_table(
|
||||
table_auto(Plots::Table)
|
||||
.col(pk_auto(Plots::Id))
|
||||
.col(string_uniq(Plots::Name))
|
||||
.col(string(Plots::Holder))
|
||||
.col(integer(Plots::Area))
|
||||
.to_owned(),
|
||||
)
|
||||
.await?;
|
||||
manager
|
||||
.create_index(
|
||||
Index::create()
|
||||
.name("idx_plots_holder")
|
||||
.table(Plots::Table)
|
||||
.col(Plots::Holder)
|
||||
.to_owned(),
|
||||
)
|
||||
.await
|
||||
}
|
||||
|
||||
async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
|
||||
manager
|
||||
.drop_table(Table::drop().table(Plots::Table).to_owned())
|
||||
.await
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(DeriveIden)]
|
||||
enum Plots {
|
||||
Table,
|
||||
Id,
|
||||
Name,
|
||||
Holder,
|
||||
Area,
|
||||
}
|
||||
```
|
||||
|
||||
Y otra, más adelante, añade una columna opcional:
|
||||
|
||||
```rust,no_run
|
||||
// src/migration/m20261101_000002_add_plot_notes.rs
|
||||
use pagetop_seaorm::migration::*;
|
||||
|
||||
pub struct Migration;
|
||||
|
||||
#[pagetop::async_trait]
|
||||
impl MigrationTrait for Migration {
|
||||
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
|
||||
manager
|
||||
.alter_table(
|
||||
Table::alter()
|
||||
.table(Plots::Table)
|
||||
.add_column(text_null(Plots::Notes))
|
||||
.to_owned(),
|
||||
)
|
||||
.await
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(DeriveIden)]
|
||||
enum Plots {
|
||||
Table,
|
||||
Notes,
|
||||
}
|
||||
```
|
||||
|
||||
Las funciones de columna siguen un patrón: `string()`, `integer()`, `boolean()`, `date()`... son
|
||||
obligatorias; con `_null` admiten nulos y con `_uniq` son únicas. `table_auto()` añade las columnas
|
||||
`created_at` y `updated_at`.
|
||||
|
||||
## 4. Aplícalas al arrancar
|
||||
|
||||
En `src/lib.rs`, declara el módulo y aplica las migraciones en `initialize()`, en orden:
|
||||
|
||||
```rust,ignore
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_seaorm::install_migrations;
|
||||
|
||||
mod migration {
|
||||
pub mod m20261015_000001_create_plots;
|
||||
pub mod m20261101_000002_add_plot_notes;
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
// ...
|
||||
|
||||
async fn initialize(&self) -> Result<(), BoxError> {
|
||||
install_migrations!(
|
||||
m20261015_000001_create_plots,
|
||||
m20261101_000002_add_plot_notes,
|
||||
)?;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Cada migración aplicada queda anotada en la tabla `seaql_migrations`, así que en los arranques
|
||||
siguientes sólo se aplican las nuevas. Si una falla, la aplicación no arranca.
|
||||
|
||||
## 5. Define las entidades
|
||||
|
||||
Una entidad describe una fila. El *struct* se llama `Model` y sus campos son públicos; a partir de
|
||||
él, `DeriveEntityModel` genera `Entity`, `Column` y `ActiveModel`:
|
||||
|
||||
```rust,no_run
|
||||
// src/entity/plot.rs
|
||||
use pagetop_seaorm::db::*;
|
||||
|
||||
#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
#[sea_orm(table_name = "plots")]
|
||||
pub struct Model {
|
||||
#[sea_orm(primary_key)]
|
||||
pub id: i32,
|
||||
pub name: String,
|
||||
pub holder: String,
|
||||
pub area: i32,
|
||||
pub notes: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
pub enum Relation {}
|
||||
|
||||
impl ActiveModelBehavior for ActiveModel {}
|
||||
```
|
||||
|
||||
Una columna que admite nulos es un `Option` en la entidad.
|
||||
|
||||
## 6. Consulta los datos
|
||||
|
||||
Todas las consultas reciben el *pool* con `dbconn()`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop_seaorm::db::*;
|
||||
# mod plot {
|
||||
# use pagetop_seaorm::db::*;
|
||||
# #[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
# #[sea_orm(table_name = "plots")]
|
||||
# pub struct Model {
|
||||
# #[sea_orm(primary_key)]
|
||||
# pub id: i32,
|
||||
# pub name: String,
|
||||
# pub holder: String,
|
||||
# pub area: i32,
|
||||
# pub notes: Option<String>,
|
||||
# }
|
||||
# #[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
# pub enum Relation {}
|
||||
# impl ActiveModelBehavior for ActiveModel {}
|
||||
# }
|
||||
async fn examples() -> Result<(), DbErr> {
|
||||
// All of them, ordered.
|
||||
let plots = plot::Entity::find()
|
||||
.order_by_asc(plot::Column::Name)
|
||||
.all(dbconn())
|
||||
.await?;
|
||||
|
||||
// Filtered, and by primary key.
|
||||
let large = plot::Entity::find()
|
||||
.filter(plot::Column::Area.gte(20))
|
||||
.all(dbconn())
|
||||
.await?;
|
||||
let first = plot::Entity::find_by_id(1).one(dbconn()).await?;
|
||||
|
||||
// Insert.
|
||||
let added = plot::ActiveModel {
|
||||
name: Set("C3".into()),
|
||||
holder: Set("Marta".into()),
|
||||
area: Set(15),
|
||||
..Default::default()
|
||||
}
|
||||
.insert(dbconn())
|
||||
.await?;
|
||||
|
||||
// Update only some columns.
|
||||
let mut changed = added.into_active_model();
|
||||
changed.holder = Set("Luke".into());
|
||||
changed.update(dbconn()).await?;
|
||||
|
||||
// Delete.
|
||||
plot::Entity::delete_by_id(3).exec(dbconn()).await?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Para un listado paginado, `paginate()` devuelve la página pedida con el total de elementos y de
|
||||
páginas, justo lo que necesita un [`Pager`](tables.md#3-pagina-el-listado):
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop_seaorm::db::*;
|
||||
# mod plot {
|
||||
# use pagetop_seaorm::db::*;
|
||||
# #[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
# #[sea_orm(table_name = "plots")]
|
||||
# pub struct Model {
|
||||
# #[sea_orm(primary_key)]
|
||||
# pub id: i32,
|
||||
# pub name: String,
|
||||
# }
|
||||
# #[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
# pub enum Relation {}
|
||||
# impl ActiveModelBehavior for ActiveModel {}
|
||||
# }
|
||||
# async fn f(page_number: u64) -> Result<(), DbErr> {
|
||||
let page = paginate(plot::Entity::find().order_by_asc(plot::Column::Name), page_number, 20).await?;
|
||||
// page.items, page.total, page.page, page.per_page, page.total_pages
|
||||
# Ok(())
|
||||
# }
|
||||
```
|
||||
|
||||
Y para varias operaciones que deben aplicarse todas o ninguna, una transacción. Si cualquiera de
|
||||
ellas falla, se deshacen todas: el intercambio de titulares nunca se queda a medias:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop_seaorm::db::*;
|
||||
# mod plot {
|
||||
# use pagetop_seaorm::db::*;
|
||||
# #[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
# #[sea_orm(table_name = "plots")]
|
||||
# pub struct Model {
|
||||
# #[sea_orm(primary_key)]
|
||||
# pub id: i32,
|
||||
# pub holder: String,
|
||||
# }
|
||||
# #[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
# pub enum Relation {}
|
||||
# impl ActiveModelBehavior for ActiveModel {}
|
||||
# }
|
||||
# async fn f() -> Result<(), DbErr> {
|
||||
// Swaps the holders of two plots.
|
||||
dbconn()
|
||||
.transaction::<_, (), DbErr>(|txn| {
|
||||
Box::pin(async move {
|
||||
plot::ActiveModel {
|
||||
id: Unchanged(1),
|
||||
holder: Set("Luke".into()),
|
||||
..Default::default()
|
||||
}
|
||||
.update(txn)
|
||||
.await?;
|
||||
plot::ActiveModel {
|
||||
id: Unchanged(2),
|
||||
holder: Set("Ana".into()),
|
||||
..Default::default()
|
||||
}
|
||||
.update(txn)
|
||||
.await?;
|
||||
Ok(())
|
||||
})
|
||||
})
|
||||
.await
|
||||
.map_err(flatten_txn_err)
|
||||
# }
|
||||
```
|
||||
|
||||
`flatten_txn_err` convierte el error de la transacción en un `DbErr` normal, para seguir usando
|
||||
`?`.
|
||||
|
||||
## 7. Relaciona tablas
|
||||
|
||||
Cada parcela da varias cosechas. La tabla `harvests` guarda el `id` de su parcela en `plot_id`, con
|
||||
una clave ajena que impide apuntar a una parcela que no existe y borra sus cosechas si se borra la
|
||||
parcela:
|
||||
|
||||
```rust,no_run
|
||||
// src/migration/m20261120_000003_create_harvests.rs
|
||||
use pagetop_seaorm::migration::*;
|
||||
|
||||
pub struct Migration;
|
||||
|
||||
#[pagetop::async_trait]
|
||||
impl MigrationTrait for Migration {
|
||||
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
|
||||
manager
|
||||
.create_table(
|
||||
table_auto(Harvests::Table)
|
||||
.col(pk_auto(Harvests::Id))
|
||||
.col(integer(Harvests::PlotId))
|
||||
.col(string(Harvests::Crop))
|
||||
.col(integer(Harvests::Kilos))
|
||||
.foreign_key(
|
||||
ForeignKey::create()
|
||||
.name("fk_harvests_plot")
|
||||
.from(Harvests::Table, Harvests::PlotId)
|
||||
.to(Plots::Table, Plots::Id)
|
||||
.on_delete(ForeignKeyAction::Cascade),
|
||||
)
|
||||
.to_owned(),
|
||||
)
|
||||
.await
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(DeriveIden)]
|
||||
enum Harvests {
|
||||
Table,
|
||||
Id,
|
||||
PlotId,
|
||||
Crop,
|
||||
Kilos,
|
||||
}
|
||||
|
||||
#[derive(DeriveIden)]
|
||||
enum Plots {
|
||||
Table,
|
||||
Id,
|
||||
}
|
||||
```
|
||||
|
||||
La relación se declara en las dos entidades. La cosecha **pertenece a** una parcela (`belongs_to`),
|
||||
indicando qué columna apunta a cuál:
|
||||
|
||||
```rust,no_run
|
||||
# mod harvest {
|
||||
// src/entity/harvest.rs
|
||||
use pagetop_seaorm::db::*;
|
||||
|
||||
#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
#[sea_orm(table_name = "harvests")]
|
||||
pub struct Model {
|
||||
#[sea_orm(primary_key)]
|
||||
pub id: i32,
|
||||
pub plot_id: i32,
|
||||
pub crop: String,
|
||||
pub kilos: i32,
|
||||
}
|
||||
|
||||
#[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
pub enum Relation {
|
||||
#[sea_orm(
|
||||
belongs_to = "super::plot::Entity",
|
||||
from = "Column::PlotId",
|
||||
to = "super::plot::Column::Id"
|
||||
)]
|
||||
Plot,
|
||||
}
|
||||
|
||||
impl Related<super::plot::Entity> for Entity {
|
||||
fn to() -> RelationDef {
|
||||
Relation::Plot.def()
|
||||
}
|
||||
}
|
||||
|
||||
impl ActiveModelBehavior for ActiveModel {}
|
||||
# }
|
||||
# mod plot {
|
||||
# use pagetop_seaorm::db::*;
|
||||
# #[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
# #[sea_orm(table_name = "plots")]
|
||||
# pub struct Model {
|
||||
# #[sea_orm(primary_key)]
|
||||
# pub id: i32,
|
||||
# }
|
||||
# #[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
# pub enum Relation {}
|
||||
# impl ActiveModelBehavior for ActiveModel {}
|
||||
# }
|
||||
```
|
||||
|
||||
Y la parcela **tiene muchas** cosechas (`has_many`). Su `Relation`, vacía hasta ahora, queda así:
|
||||
|
||||
```rust,ignore
|
||||
// src/entity/plot.rs
|
||||
#[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
pub enum Relation {
|
||||
#[sea_orm(has_many = "super::harvest::Entity")]
|
||||
Harvests,
|
||||
}
|
||||
|
||||
impl Related<super::harvest::Entity> for Entity {
|
||||
fn to() -> RelationDef {
|
||||
Relation::Harvests.def()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Con las dos declaradas, puedes ir de una a otra sin escribir el `JOIN`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop_seaorm::db::*;
|
||||
# mod plot {
|
||||
# use pagetop_seaorm::db::*;
|
||||
# #[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
# #[sea_orm(table_name = "plots")]
|
||||
# pub struct Model {
|
||||
# #[sea_orm(primary_key)]
|
||||
# pub id: i32,
|
||||
# pub name: String,
|
||||
# }
|
||||
# #[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
# pub enum Relation {
|
||||
# #[sea_orm(has_many = "super::harvest::Entity")]
|
||||
# Harvests,
|
||||
# }
|
||||
# impl Related<super::harvest::Entity> for Entity {
|
||||
# fn to() -> RelationDef {
|
||||
# Relation::Harvests.def()
|
||||
# }
|
||||
# }
|
||||
# impl ActiveModelBehavior for ActiveModel {}
|
||||
# }
|
||||
# mod harvest {
|
||||
# use pagetop_seaorm::db::*;
|
||||
# #[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
# #[sea_orm(table_name = "harvests")]
|
||||
# pub struct Model {
|
||||
# #[sea_orm(primary_key)]
|
||||
# pub id: i32,
|
||||
# pub plot_id: i32,
|
||||
# pub crop: String,
|
||||
# pub kilos: i32,
|
||||
# }
|
||||
# #[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
# pub enum Relation {
|
||||
# #[sea_orm(
|
||||
# belongs_to = "super::plot::Entity",
|
||||
# from = "Column::PlotId",
|
||||
# to = "super::plot::Column::Id"
|
||||
# )]
|
||||
# Plot,
|
||||
# }
|
||||
# impl Related<super::plot::Entity> for Entity {
|
||||
# fn to() -> RelationDef {
|
||||
# Relation::Plot.def()
|
||||
# }
|
||||
# }
|
||||
# impl ActiveModelBehavior for ActiveModel {}
|
||||
# }
|
||||
# async fn f() -> Result<(), DbErr> {
|
||||
// Each harvest together with its plot, in a single query.
|
||||
let rows: Vec<(harvest::Model, Option<plot::Model>)> = harvest::Entity::find()
|
||||
.find_also_related(plot::Entity)
|
||||
.all(dbconn())
|
||||
.await?;
|
||||
|
||||
// The harvests of one plot.
|
||||
if let Some(plot) = plot::Entity::find_by_id(1).one(dbconn()).await? {
|
||||
let harvests = plot.find_related(harvest::Entity).all(dbconn()).await?;
|
||||
}
|
||||
# Ok(())
|
||||
# }
|
||||
# fn main() {}
|
||||
```
|
||||
|
||||
La parcela de `find_also_related()` es un `Option` porque, en general, la columna podría estar
|
||||
vacía; con una clave ajena obligatoria como esta, siempre llega.
|
||||
|
||||
## 8. Escribe SQL a mano
|
||||
|
||||
Para lo que no encaja en una entidad, como un total por grupos, construye la consulta con
|
||||
`db::query` y léela con `fetch_all()`. Cada fila llega sin tipo, y cada columna se extrae con
|
||||
`try_get()`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop_seaorm::db::*;
|
||||
use pagetop_seaorm::db::query::*;
|
||||
|
||||
# async fn f() -> Result<(), DbErr> {
|
||||
// Kilos by crop, the largest first.
|
||||
let stmt = Query::select()
|
||||
.column(Alias::new("crop"))
|
||||
.expr_as(Expr::col(Alias::new("kilos")).sum(), Alias::new("total"))
|
||||
.from(Alias::new("harvests"))
|
||||
.group_by_col(Alias::new("crop"))
|
||||
.order_by(Alias::new("total"), Order::Desc)
|
||||
.to_owned();
|
||||
|
||||
for row in fetch_all(&stmt).await? {
|
||||
let crop: String = row.try_get("", "crop")?;
|
||||
let total: i64 = row.try_get("", "total")?;
|
||||
println!("{crop}: {total} kg");
|
||||
}
|
||||
# Ok(())
|
||||
# }
|
||||
```
|
||||
|
||||
`fetch_one()` devuelve sólo la primera fila. Para modificar datos sin entidad, `execute()` recibe
|
||||
la sentencia como texto y devuelve cuántas filas ha cambiado:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop_seaorm::db::*;
|
||||
# async fn f() -> Result<(), DbErr> {
|
||||
let result = execute("DELETE FROM harvests WHERE kilos = 0").await?;
|
||||
println!("{} empty harvests removed", result.rows_affected());
|
||||
# Ok(())
|
||||
# }
|
||||
```
|
||||
|
||||
`execute()` envía el texto tal cual: **nunca** pegues en él datos que vengan del usuario, porque
|
||||
abrirías la puerta a la inyección de SQL. Con esos datos, usa las entidades o el constructor de
|
||||
consultas, que los escapan por ti.
|
||||
|
||||
## Comprueba
|
||||
|
||||
Una prueba con SQLite en memoria aplica las migraciones y verifica las consultas, sin tocar tu base
|
||||
de datos (ve [Usa otra configuración para las pruebas](testing.md#5-usa-otra-configuración-para-las-pruebas)):
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_seaorm::db::*;
|
||||
# use pagetop_seaorm::install_migrations;
|
||||
# mod migration {
|
||||
# pub mod m20261015_000001_create_plots {
|
||||
# use pagetop_seaorm::migration::*;
|
||||
# pub struct Migration;
|
||||
# #[pagetop::async_trait]
|
||||
# impl MigrationTrait for Migration {
|
||||
# async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
|
||||
# manager
|
||||
# .create_table(
|
||||
# table_auto(Plots::Table)
|
||||
# .col(pk_auto(Plots::Id))
|
||||
# .col(string_uniq(Plots::Name))
|
||||
# .col(string(Plots::Holder))
|
||||
# .col(integer(Plots::Area))
|
||||
# .to_owned(),
|
||||
# )
|
||||
# .await
|
||||
# }
|
||||
# }
|
||||
# #[derive(DeriveIden)]
|
||||
# enum Plots { Table, Id, Name, Holder, Area }
|
||||
# }
|
||||
# pub mod m20261101_000002_add_plot_notes {
|
||||
# use pagetop_seaorm::migration::*;
|
||||
# pub struct Migration;
|
||||
# #[pagetop::async_trait]
|
||||
# impl MigrationTrait for Migration {
|
||||
# async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
|
||||
# manager
|
||||
# .alter_table(
|
||||
# Table::alter()
|
||||
# .table(Plots::Table)
|
||||
# .add_column(text_null(Plots::Notes))
|
||||
# .to_owned(),
|
||||
# )
|
||||
# .await
|
||||
# }
|
||||
# }
|
||||
# #[derive(DeriveIden)]
|
||||
# enum Plots { Table, Notes }
|
||||
# }
|
||||
# pub mod m20261120_000003_create_harvests {
|
||||
# use pagetop_seaorm::migration::*;
|
||||
# pub struct Migration;
|
||||
# #[pagetop::async_trait]
|
||||
# impl MigrationTrait for Migration {
|
||||
# async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
|
||||
# manager
|
||||
# .create_table(
|
||||
# table_auto(Harvests::Table)
|
||||
# .col(pk_auto(Harvests::Id))
|
||||
# .col(integer(Harvests::PlotId))
|
||||
# .col(string(Harvests::Crop))
|
||||
# .col(integer(Harvests::Kilos))
|
||||
# .foreign_key(
|
||||
# ForeignKey::create()
|
||||
# .name("fk_harvests_plot")
|
||||
# .from(Harvests::Table, Harvests::PlotId)
|
||||
# .to(Plots::Table, Plots::Id)
|
||||
# .on_delete(ForeignKeyAction::Cascade),
|
||||
# )
|
||||
# .to_owned(),
|
||||
# )
|
||||
# .await
|
||||
# }
|
||||
# }
|
||||
# #[derive(DeriveIden)]
|
||||
# enum Harvests { Table, Id, PlotId, Crop, Kilos }
|
||||
# #[derive(DeriveIden)]
|
||||
# enum Plots { Table, Id }
|
||||
# }
|
||||
# }
|
||||
# mod plot {
|
||||
# use pagetop_seaorm::db::*;
|
||||
# #[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
# #[sea_orm(table_name = "plots")]
|
||||
# pub struct Model {
|
||||
# #[sea_orm(primary_key)]
|
||||
# pub id: i32,
|
||||
# pub name: String,
|
||||
# pub holder: String,
|
||||
# pub area: i32,
|
||||
# pub notes: Option<String>,
|
||||
# }
|
||||
# #[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
# pub enum Relation {
|
||||
# #[sea_orm(has_many = "super::harvest::Entity")]
|
||||
# Harvests,
|
||||
# }
|
||||
# impl Related<super::harvest::Entity> for Entity {
|
||||
# fn to() -> RelationDef {
|
||||
# Relation::Harvests.def()
|
||||
# }
|
||||
# }
|
||||
# impl ActiveModelBehavior for ActiveModel {}
|
||||
# }
|
||||
# mod harvest {
|
||||
# use pagetop_seaorm::db::*;
|
||||
# #[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
|
||||
# #[sea_orm(table_name = "harvests")]
|
||||
# pub struct Model {
|
||||
# #[sea_orm(primary_key)]
|
||||
# pub id: i32,
|
||||
# pub plot_id: i32,
|
||||
# pub crop: String,
|
||||
# pub kilos: i32,
|
||||
# }
|
||||
# #[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
|
||||
# pub enum Relation {
|
||||
# #[sea_orm(
|
||||
# belongs_to = "super::plot::Entity",
|
||||
# from = "Column::PlotId",
|
||||
# to = "super::plot::Column::Id"
|
||||
# )]
|
||||
# Plot,
|
||||
# }
|
||||
# impl Related<super::plot::Entity> for Entity {
|
||||
# fn to() -> RelationDef {
|
||||
# Relation::Plot.def()
|
||||
# }
|
||||
# }
|
||||
# impl ActiveModelBehavior for ActiveModel {}
|
||||
# }
|
||||
# pub struct Garden;
|
||||
# #[async_trait]
|
||||
# impl Extension for Garden {
|
||||
# fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
# vec![&pagetop_seaorm::SeaORM]
|
||||
# }
|
||||
# async fn initialize(&self) -> Result<(), BoxError> {
|
||||
# install_migrations!(
|
||||
# m20261015_000001_create_plots,
|
||||
# m20261101_000002_add_plot_notes,
|
||||
# m20261120_000003_create_harvests,
|
||||
# )?;
|
||||
# Ok(())
|
||||
# }
|
||||
# }
|
||||
# fn new_plot(name: &str, holder: &str, area: i32) -> plot::ActiveModel {
|
||||
# plot::ActiveModel {
|
||||
# name: Set(name.into()),
|
||||
# holder: Set(holder.into()),
|
||||
# area: Set(area),
|
||||
# ..Default::default()
|
||||
# }
|
||||
# }
|
||||
# fn new_harvest(plot_id: i32, crop: &str, kilos: i32) -> harvest::ActiveModel {
|
||||
# harvest::ActiveModel {
|
||||
# plot_id: Set(plot_id),
|
||||
# crop: Set(crop.into()),
|
||||
# kilos: Set(kilos),
|
||||
# ..Default::default()
|
||||
# }
|
||||
# }
|
||||
#[pagetop::test]
|
||||
async fn plots_and_harvests_are_stored_and_queried() {
|
||||
Application::prepare(&Garden).await;
|
||||
|
||||
for (name, holder, area) in [("A1", "Ana", 25), ("A2", "Luke", 12), ("B1", "Marta", 30)] {
|
||||
new_plot(name, holder, area).insert(dbconn()).await.unwrap();
|
||||
}
|
||||
|
||||
let large = plot::Entity::find()
|
||||
.filter(plot::Column::Area.gte(20))
|
||||
.count(dbconn())
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(large, 2);
|
||||
|
||||
let page = paginate(plot::Entity::find().order_by_asc(plot::Column::Name), 2, 2)
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!((page.total, page.total_pages), (3, 2));
|
||||
assert_eq!(page.items[0].name, "B1");
|
||||
assert_eq!(page.items[0].notes, None);
|
||||
|
||||
// Plot 1 (A1) gives two harvests and plot 3 (B1) one.
|
||||
for (plot_id, crop, kilos) in [(1, "Tomatoes", 12), (1, "Lettuces", 5), (3, "Tomatoes", 9)] {
|
||||
new_harvest(plot_id, crop, kilos).insert(dbconn()).await.unwrap();
|
||||
}
|
||||
|
||||
let a1 = plot::Entity::find_by_id(1).one(dbconn()).await.unwrap().unwrap();
|
||||
let harvests = a1.find_related(harvest::Entity).all(dbconn()).await.unwrap();
|
||||
assert_eq!(harvests.len(), 2);
|
||||
|
||||
let rows = harvest::Entity::find()
|
||||
.find_also_related(plot::Entity)
|
||||
.all(dbconn())
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(rows.iter().all(|(_, plot)| plot.is_some()));
|
||||
|
||||
use pagetop_seaorm::db::query::*;
|
||||
let stmt = Query::select()
|
||||
.column(Alias::new("crop"))
|
||||
.expr_as(Expr::col(Alias::new("kilos")).sum(), Alias::new("total"))
|
||||
.from(Alias::new("harvests"))
|
||||
.group_by_col(Alias::new("crop"))
|
||||
.order_by(Alias::new("total"), Order::Desc)
|
||||
.to_owned();
|
||||
let first = &fetch_all(&stmt).await.unwrap()[0];
|
||||
let crop: String = first.try_get("", "crop").unwrap();
|
||||
let total: i64 = first.try_get("", "total").unwrap();
|
||||
assert_eq!((crop.as_str(), total), ("Tomatoes", 21));
|
||||
}
|
||||
```
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Añadir usuarios y permisos](users.md): `pagetop-user` guarda usuarios y sesiones en esta misma
|
||||
base de datos.
|
||||
- [Ordenar y paginar sin recargar](htmx-tables.md): un listado paginado con HTMX.
|
||||
166
doc/v0.6/es/src/how-to/deployment.md
Normal file
166
doc/v0.6/es/src/how-to/deployment.md
Normal file
|
|
@ -0,0 +1,166 @@
|
|||
# Desplegar en producción
|
||||
|
||||
**Objetivo:** compilar la aplicación en modo optimizado y ponerla en marcha en un servidor, como
|
||||
servicio del sistema o en un contenedor, detrás de un proxy inverso con HTTPS.
|
||||
|
||||
## 1. Compila para producción
|
||||
|
||||
```sh
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
Para un binario más pequeño y rápido, añade a tu `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[profile.release]
|
||||
opt-level = 3
|
||||
lto = "fat"
|
||||
codegen-units = 1
|
||||
strip = true
|
||||
```
|
||||
|
||||
El ejecutable de `target/release/` incluye estilos, *scripts*, imágenes y traducciones. Sólo
|
||||
necesita, a su lado, el directorio `config/`.
|
||||
|
||||
## 2. Ponla en marcha
|
||||
|
||||
```text
|
||||
/opt/my-app/
|
||||
├── my-app <- the binary
|
||||
└── config/
|
||||
├── common.toml
|
||||
├── production.toml
|
||||
└── local.production.toml <- secrets of this server
|
||||
```
|
||||
|
||||
```sh
|
||||
cd /opt/my-app
|
||||
PAGETOP_RUN_MODE=production ./my-app
|
||||
```
|
||||
|
||||
O, desde cualquier directorio, indicando dónde está la configuración:
|
||||
|
||||
```sh
|
||||
CONFIG_DIR=/opt/my-app/config PAGETOP_RUN_MODE=production /opt/my-app/my-app
|
||||
```
|
||||
|
||||
Los secretos pueden ir también en variables de entorno en lugar de `local.production.toml`:
|
||||
cualquier clave se sobrescribe con `PAGETOP_<SECCIÓN>__<CLAVE>` (p. ej.
|
||||
`PAGETOP_DATABASE__DB_PASS`), como explica la
|
||||
[referencia de la configuración](../reference/configuration.md).
|
||||
|
||||
Recuerda que, por defecto, el servidor sólo escucha en `localhost`. Para aceptar conexiones de
|
||||
fuera, o de un proxy en otro equipo, fija `bind_address = "0.0.0.0"` en `[server]`.
|
||||
|
||||
## 3. Como servicio del sistema
|
||||
|
||||
PageTop se detiene de forma ordenada con `SIGTERM`, la señal que envían `systemd` o Docker: deja de
|
||||
aceptar conexiones, termina las peticiones en curso, espera a las tareas de `pagetop-cron` que estén
|
||||
en marcha y vuelca las trazas pendientes. Una unidad de `systemd` sencilla:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=My PageTop application
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
WorkingDirectory=/opt/my-app
|
||||
Environment=PAGETOP_RUN_MODE=production
|
||||
EnvironmentFile=-/etc/my-app/secrets.env
|
||||
ExecStart=/opt/my-app/my-app
|
||||
Restart=on-failure
|
||||
User=my-app
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
`EnvironmentFile` es opcional (el `-` lo admite ausente): un archivo legible sólo por `root`, con
|
||||
una variable por línea, como `PAGETOP_DATABASE__DB_PASS=secret`.
|
||||
|
||||
## 4. En un contenedor
|
||||
|
||||
El binario no necesita nada a su lado salvo `config/`, así que la imagen final puede ser mínima. Un
|
||||
`Dockerfile` en dos fases, que compila en una imagen de Rust y copia sólo el resultado:
|
||||
|
||||
```dockerfile
|
||||
FROM rust:1.88 AS build
|
||||
WORKDIR /src
|
||||
COPY . .
|
||||
RUN cargo build --release
|
||||
|
||||
FROM debian:bookworm-slim
|
||||
WORKDIR /app
|
||||
COPY --from=build /src/target/release/my-app /app/my-app
|
||||
COPY config /app/config
|
||||
ENV PAGETOP_RUN_MODE=production
|
||||
EXPOSE 8080
|
||||
CMD ["/app/my-app"]
|
||||
```
|
||||
|
||||
Dentro del contenedor, el servidor debe escuchar en todas las interfaces: pon
|
||||
`bind_address = "0.0.0.0"` en `config/production.toml`. Docker detiene los contenedores con
|
||||
`SIGTERM`, que PageTop atiende cerrando de forma ordenada. Los secretos no van en la imagen: se
|
||||
pasan al arrancar el contenedor, por ejemplo con `docker run --env-file secrets.env`.
|
||||
|
||||
## 5. Detrás de un proxy inverso
|
||||
|
||||
Para HTTPS, certificados y compresión, pon delante un proxy inverso como nginx o Caddy. Un ejemplo
|
||||
con nginx:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name my-app.example.com;
|
||||
|
||||
# ssl_certificate ... ssl_certificate_key ...
|
||||
|
||||
# Allows uploads up to upload.max_request_size (nginx accepts 1 MiB by default).
|
||||
client_max_body_size 32m;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8080;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Con el proxy delante, deja `bind_address = "localhost"` (el valor por defecto): así sólo el proxy
|
||||
llega a la aplicación.
|
||||
|
||||
Todas las conexiones llegan entonces desde el proxy. Para que la aplicación conozca la dirección de
|
||||
cada visitante, que usan por ejemplo los límites por IP de `pagetop-user`, indica la cabecera en
|
||||
la que el proxy la escribe:
|
||||
|
||||
```toml
|
||||
[server]
|
||||
client_ip_header = "X-Forwarded-For"
|
||||
```
|
||||
|
||||
Si la cabecera trae varias direcciones, vale la última, la que añade el proxy: las anteriores las
|
||||
envía el navegador y podrían ser falsas. Configúrala sólo si todas las peticiones pasan por el
|
||||
proxy y éste escribe siempre la cabecera, como hace `$proxy_add_x_forwarded_for` en el ejemplo.
|
||||
|
||||
Conserva la línea `proxy_set_header Host $host;`. La protección contra CSRF compara la cabecera
|
||||
`Origin` del navegador con `Host` cuando el navegador no envía `Sec-Fetch-Site` (los antiguos, o
|
||||
cualquiera en una conexión HTTP sin cifrar fuera de `localhost`). Si el proxy cambia `Host` por
|
||||
`127.0.0.1:8080`, esos navegadores reciben un `403` al enviar cualquier formulario.
|
||||
|
||||
## Comprueba
|
||||
|
||||
```sh
|
||||
curl -I https://my-app.example.com/
|
||||
```
|
||||
|
||||
Responde `200` a través del proxy. En el servidor, `systemctl status my-app` (o `docker logs`)
|
||||
muestra las trazas de arranque, y `systemctl stop my-app` detiene la aplicación sin cortar las
|
||||
peticiones en curso.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Registrar trazas](logging.md): trazas en archivos con rotación.
|
||||
- [Programar tareas periódicas](cron.md#6-con-varias-instancias-elige-el-modo): con varias
|
||||
instancias, quién ejecuta las tareas.
|
||||
- [Opciones de configuración](../reference/configuration.md).
|
||||
286
doc/v0.6/es/src/how-to/error-pages.md
Normal file
286
doc/v0.6/es/src/how-to/error-pages.md
Normal file
|
|
@ -0,0 +1,286 @@
|
|||
# Mostrar páginas de error
|
||||
|
||||
**Objetivo:** responder con una página de error cuando algo no sale bien (un recurso que no existe,
|
||||
un acceso no permitido, un fallo al leer los datos) sin que el visitante pierda la navegación del
|
||||
sitio, responder con JSON cuando quien llama es una API, y saber qué ocurre cuando el fallo es
|
||||
grave.
|
||||
|
||||
Las cosas fallan: alguien escribe mal una dirección, un archivo desaparece o la base de datos no
|
||||
responde. PageTop distingue dos niveles. Los **errores controlados** los decide tu código y se
|
||||
muestran como una página más del sitio, con su cabecera, su menú y su pie. Los **fallos graves**
|
||||
(un `panic!`) los atrapa PageTop y responde con una página mínima. Esta guía recorre los dos.
|
||||
|
||||
## 1. Devuelve el error desde el *handler*
|
||||
|
||||
Un *handler* que construye una página devuelve `Result<Markup, ErrorPage>`. Para responder con un
|
||||
error, devuelve la variante que corresponda:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
const PLOTS: [(&str, &str); 2] = [("a1", "Ana"), ("b2", "Luke")];
|
||||
|
||||
async fn plot(
|
||||
request: HttpRequest,
|
||||
web::Path(code): web::Path<String>,
|
||||
) -> Result<Markup, ErrorPage> {
|
||||
let Some((_, holder)) = PLOTS.iter().find(|(c, _)| *c == code) else {
|
||||
return Err(ErrorPage::NotFound(Some(request)));
|
||||
};
|
||||
let holder = holder.to_string();
|
||||
Page::new(request)
|
||||
.with_title(Lc::n(code))
|
||||
.with_child(Html::with(move |_| html! { p { "Holder: " (holder) } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
`/plots/a1` muestra la parcela y `/plots/z9` responde con un 404 que conserva el aspecto del sitio.
|
||||
Elige la variante por lo que ha pasado:
|
||||
|
||||
| Variante | Código | Cuándo |
|
||||
|---|---|---|
|
||||
| `ErrorPage::BadRequest` | 400 | Los datos de la petición no tienen sentido |
|
||||
| `ErrorPage::AccessDenied` | 403 | El usuario no tiene permiso para verlo |
|
||||
| `ErrorPage::NotFound` | 404 | Lo que se pide no existe |
|
||||
| `ErrorPage::InternalError` | 500 | Algo ha fallado en el servidor |
|
||||
| `ErrorPage::ServiceUnavailable` | 503 | El servicio no puede atender ahora (mantenimiento, carga) |
|
||||
| `ErrorPage::GatewayTimeout` | 504 | Un servicio externo no ha respondido a tiempo |
|
||||
|
||||
Pásale siempre la petición (`Some(request)`): con ella la página de error sale en el idioma del
|
||||
visitante y sabe quién es, por ejemplo para mostrar su menú de cuenta. Con `None` también se
|
||||
muestra, pero sin esos datos.
|
||||
|
||||
Las rutas que no existen no necesitan nada: PageTop responde por sí solo con la misma página 404.
|
||||
|
||||
## 2. Convierte tus errores en un `ErrorPage`
|
||||
|
||||
Lo normal es que el error venga de otra parte: un archivo que no se puede leer, una consulta que
|
||||
falla. Conviértelo con `map_err()` y sigue usando `?`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
async fn report(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
let text = std::fs::read_to_string("data/report.txt").map_err(|err| {
|
||||
trace::error!(%err, "Cannot read the report");
|
||||
ErrorPage::InternalError(Some(request.clone()))
|
||||
})?;
|
||||
|
||||
Page::new(request)
|
||||
.with_child(Html::with(move |_| html! { pre { (text) } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
Clonar la petición es barato, así que no te preocupes por el `request.clone()`.
|
||||
|
||||
## 3. Guarda los detalles en el registro, no en la página
|
||||
|
||||
La página de error **nunca** muestra el motivo del fallo: dice qué ha pasado en términos que
|
||||
entiende el visitante («se ha producido un error interno») y nada más. Es deliberado: un mensaje
|
||||
de la base de datos o una ruta de un archivo darían pistas a quien no debe tenerlas.
|
||||
|
||||
Los detalles van al registro, como en el ejemplo anterior con `trace::error!`. Allí los encontrarás
|
||||
cuando tengas que averiguar qué ocurrió (ve [Registrar trazas](logging.md)).
|
||||
|
||||
## 4. Cambia su contenido desde el tema
|
||||
|
||||
Los textos de las páginas de error vienen traducidos de serie. Si quieres otro contenido, por
|
||||
ejemplo una página 404 con un enlace a la portada, el tema activo puede sustituirlo con
|
||||
`error_403()`, `error_404()` y `error_fatal()` (este último para 400, 500, 503 y 504). Lo explica
|
||||
[Crear un tema](themes.md#6-cambia-las-páginas-de-error).
|
||||
|
||||
## 5. Ten en cuenta HTMX
|
||||
|
||||
Si la petición la hace HTMX, recuerda que HTMX **no sustituye** el contenido cuando la respuesta es
|
||||
un 4xx o un 5xx: el usuario no vería nada. Para avisar de un error en un fragmento, responde con un
|
||||
200 y el mensaje, o cambia el destino con `HtmxResponse` (ve [Dirigir al navegador desde el
|
||||
servidor](htmx-responses.md)).
|
||||
|
||||
## 6. Los fallos graves
|
||||
|
||||
Un `panic!` en un *handler*, un componente o el tema no tumba el servidor. PageTop lo atrapa,
|
||||
anota el motivo en el registro y responde con un 500 y una página mínima, sin tema ni componentes:
|
||||
después de un fallo así no es seguro volver a usar el mismo ciclo de renderizado que acaba de
|
||||
fallar.
|
||||
|
||||
```rust,no_run
|
||||
async fn boom() -> &'static str {
|
||||
panic!("This should never happen");
|
||||
}
|
||||
```
|
||||
|
||||
Es la red de seguridad, no una forma de gestionar errores: reserva `panic!` para lo que de verdad
|
||||
no puede ocurrir y devuelve un `ErrorPage` en todo lo demás.
|
||||
|
||||
## 7. Errores de una API JSON
|
||||
|
||||
Una ruta que devuelve JSON no debe responder a un error con una página HTML: quien la llama es un
|
||||
programa, y espera JSON. Define un tipo de error con [`thiserror`](https://docs.rs/thiserror),
|
||||
decide en `IntoResponse` el código de cada variante y devuelve el mensaje en un cuerpo JSON:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use serde::Serialize;
|
||||
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
enum ApiError {
|
||||
#[error("Plot {0} not found")]
|
||||
PlotNotFound(String),
|
||||
#[error("The harvest must weigh more than zero kilos")]
|
||||
InvalidKilos,
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct ErrorBody {
|
||||
status: u16,
|
||||
error: String,
|
||||
}
|
||||
|
||||
impl web::IntoResponse for ApiError {
|
||||
fn into_response(self) -> Response {
|
||||
let status = match self {
|
||||
Self::PlotNotFound(_) => web::http::StatusCode::NOT_FOUND,
|
||||
Self::InvalidKilos => web::http::StatusCode::UNPROCESSABLE_ENTITY,
|
||||
};
|
||||
let body = ErrorBody { status: status.as_u16(), error: self.to_string() };
|
||||
(status, Json(body)).into_response()
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct Plot {
|
||||
code: String,
|
||||
holder: &'static str,
|
||||
}
|
||||
|
||||
async fn api_plot(web::Path(code): web::Path<String>) -> Result<Json<Plot>, ApiError> {
|
||||
match code.as_str() {
|
||||
"a1" => Ok(Json(Plot { code, holder: "Ana" })),
|
||||
_ => Err(ApiError::PlotNotFound(code)),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`/api/plots/z9` responde con un 404 y `{"status":404,"error":"Plot z9 not found"}`. Como el tipo
|
||||
implementa `IntoResponse`, el *handler* sigue usando `?` con normalidad.
|
||||
|
||||
Aquí los mensajes son para quien usa la API, así que se envían tal cual. Un error interno (una
|
||||
consulta que falla) es otra cosa: regístralo con `trace::error!` y responde con un 500 y un mensaje
|
||||
genérico, igual que haría una página de error.
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
const PLOTS: [(&str, &str); 2] = [("a1", "Ana"), ("b2", "Luke")];
|
||||
|
||||
struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/plots/{code}", web::get(plot))
|
||||
.route("/report", web::get(report))
|
||||
.route("/boom", web::get(boom))
|
||||
}
|
||||
}
|
||||
|
||||
async fn plot(
|
||||
request: HttpRequest,
|
||||
web::Path(code): web::Path<String>,
|
||||
) -> Result<Markup, ErrorPage> {
|
||||
let Some((_, holder)) = PLOTS.iter().find(|(c, _)| *c == code) else {
|
||||
return Err(ErrorPage::NotFound(Some(request)));
|
||||
};
|
||||
let holder = holder.to_string();
|
||||
Page::new(request)
|
||||
.with_title(Lc::n(code))
|
||||
.with_child(Html::with(move |_| html! { p { "Holder: " (holder) } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn report(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
let text = std::fs::read_to_string("data/report.txt").map_err(|err| {
|
||||
trace::error!(%err, "Cannot read the report");
|
||||
ErrorPage::InternalError(Some(request.clone()))
|
||||
})?;
|
||||
|
||||
Page::new(request)
|
||||
.with_child(Html::with(move |_| html! { pre { (text) } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn boom() -> &'static str {
|
||||
panic!("This should never happen");
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Garden).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
Arranca la aplicación con `cargo run` y prueba cada caso:
|
||||
|
||||
```sh
|
||||
curl -i http://localhost:8080/plots/a1 # 200 OK, the plot page
|
||||
curl -i http://localhost:8080/plots/z9 # 404 Not Found, with the site's error page
|
||||
curl -i http://localhost:8080/report # 500 until data/report.txt exists (reason in the log)
|
||||
curl -i http://localhost:8080/boom # 500 with the minimal page; the panic is in the log
|
||||
```
|
||||
|
||||
En el navegador, la 404 y la 500 tienen la cabecera y el pie del sitio; la de `/boom`, no.
|
||||
|
||||
También puedes comprobarlo en una prueba (ve [Probar rutas y componentes](testing.md)):
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
# const PLOTS: [(&str, &str); 2] = [("a1", "Ana"), ("b2", "Luke")];
|
||||
# struct Garden;
|
||||
# #[async_trait]
|
||||
# impl Extension for Garden {
|
||||
# fn configure_router(&self, router: Router) -> Router {
|
||||
# router.route("/plots/{code}", web::get(plot))
|
||||
# }
|
||||
# }
|
||||
# async fn plot(
|
||||
# request: HttpRequest,
|
||||
# web::Path(code): web::Path<String>,
|
||||
# ) -> Result<Markup, ErrorPage> {
|
||||
# let Some((_, holder)) = PLOTS.iter().find(|(c, _)| *c == code) else {
|
||||
# return Err(ErrorPage::NotFound(Some(request)));
|
||||
# };
|
||||
# let holder = holder.to_string();
|
||||
# Page::new(request)
|
||||
# .with_title(Lc::n(code))
|
||||
# .with_child(Html::with(move |_| html! { p { "Holder: " (holder) } }))
|
||||
# .render()
|
||||
# .await
|
||||
# }
|
||||
#[pagetop::test]
|
||||
async fn an_unknown_plot_shows_the_not_found_page() {
|
||||
let app = web::test::init_router(Application::prepare(&Garden).await.test());
|
||||
|
||||
let request = web::test::TestRequest::get().uri("/plots/z9").to_request();
|
||||
let response = web::test::send_request(&app, request).await;
|
||||
|
||||
assert_eq!(response.status(), web::http::StatusCode::NOT_FOUND);
|
||||
let body = web::test::read_body_text(response).await;
|
||||
assert!(body.contains("The requested page could not be found."));
|
||||
}
|
||||
```
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Crear un tema](themes.md#6-cambia-las-páginas-de-error): otro contenido para las páginas de
|
||||
error.
|
||||
- [Registrar trazas](logging.md): dónde acaban los detalles de cada fallo.
|
||||
- [Añadir usuarios y permisos](users.md): `AccessDenied` en acción.
|
||||
189
doc/v0.6/es/src/how-to/extensions.md
Normal file
189
doc/v0.6/es/src/how-to/extensions.md
Normal file
|
|
@ -0,0 +1,189 @@
|
|||
# Crear una extensión
|
||||
|
||||
**Objetivo:** empaquetar una funcionalidad (rutas, componentes, ajustes, traducciones) en una
|
||||
extensión que cualquier aplicación pueda añadir con una línea.
|
||||
|
||||
Una extensión es una estructura que implementa `Extension`. Todos sus métodos son opcionales:
|
||||
sobrescribe sólo los que necesites.
|
||||
|
||||
| Método | Para qué |
|
||||
|---|---|
|
||||
| `name()`, `description()` | Nombre y descripción legibles (con `Lc`, traducibles) |
|
||||
| `dependencies()` | Extensiones que deben arrancar antes |
|
||||
| `settings()` | [Ajustes](configuration.md#5-ajustes-de-tu-extensión) que se cargan al arrancar |
|
||||
| `actions()` | [Acciones](actions.md) que registra |
|
||||
| `initialize()` | Código que se ejecuta al arrancar |
|
||||
| `configure_router()` | [Rutas](routes.md) |
|
||||
| `configure_middleware()` | Capas que envuelven las rutas de **todas** las extensiones |
|
||||
| `configure_static_files()` | [Recursos estáticos](assets.md) |
|
||||
| `theme()` | Si la extensión es un [tema](themes.md) |
|
||||
|
||||
## 1. Una extensión completa
|
||||
|
||||
Un pequeño blog: declara sus dependencias, añade un enlace al pie de todas las páginas y registra
|
||||
sus rutas.
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
pub struct Blog;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Blog {
|
||||
fn name(&self) -> Lc {
|
||||
Lc::n("Blog")
|
||||
}
|
||||
|
||||
fn description(&self) -> Lc {
|
||||
Lc::n("Posts and news")
|
||||
}
|
||||
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_bootsier::Bootsier]
|
||||
}
|
||||
|
||||
async fn initialize(&self) -> Result<(), BoxError> {
|
||||
InRegion::Global(&CoreRegions::Footer)
|
||||
.add(Html::with(|cx| html! { a href=(cx.route("/blog")) { "Blog" } }));
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/blog", web::get(index))
|
||||
.route("/blog/{slug}", web::get(post))
|
||||
}
|
||||
}
|
||||
|
||||
async fn index(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request).with_title(Lc::n("Blog")).render().await
|
||||
}
|
||||
|
||||
async fn post(
|
||||
request: HttpRequest,
|
||||
web::Path(slug): web::Path<String>,
|
||||
) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_child(Html::with(move |_| html! { h1 { (slug) } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
Para usarla, la aplicación sólo tiene que declararla como dependencia:
|
||||
|
||||
```rust,ignore
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&blog::Blog]
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Declara sus dependencias
|
||||
|
||||
`dependencies()` construye el árbol de la aplicación. PageTop garantiza que cada dependencia está
|
||||
registrada e inicializada **antes** que la extensión que la declara. Es independiente de las
|
||||
dependencias de `Cargo.toml`, que sólo resuelven la compilación.
|
||||
|
||||
## 3. Inicialízala al arrancar
|
||||
|
||||
`initialize()` es `async`: puede conectar con una base de datos, aplicar migraciones o cargar
|
||||
datos. Si devuelve un error, la aplicación **no arranca**: PageTop muestra el error con sus
|
||||
causas y termina. Gracias a `BoxError`, puedes propagar cualquier error con `?`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
pub struct Catalog;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Catalog {
|
||||
async fn initialize(&self) -> Result<(), BoxError> {
|
||||
let data = std::fs::read_to_string("catalog.json")?;
|
||||
trace::info!("Catalog loaded: {} bytes", data.len());
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`initialize()` se ejecuta cada vez que se prepara la aplicación, también en las pruebas. Lo que
|
||||
debe funcionar sólo mientras la aplicación está **en marcha**, como una tarea en segundo plano que
|
||||
vacía una cola, se lanza en `start()`: sólo lo llama `run()`, una vez enlazado el puerto y antes
|
||||
de la primera petición, y nunca las pruebas. Su pareja, `shutdown()`, se llama al detener la
|
||||
aplicación, cuando ya han terminado las peticiones en curso. El ejemplo lanza la tarea con
|
||||
[Tokio](https://tokio.rs), que debes añadir a tu `Cargo.toml`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
pub struct Outbox;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Outbox {
|
||||
async fn start(&self) -> Result<(), BoxError> {
|
||||
tokio::spawn(async {
|
||||
loop {
|
||||
tokio::time::sleep(std::time::Duration::from_secs(60)).await;
|
||||
trace::info!("Flushing the outbox");
|
||||
}
|
||||
});
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn shutdown(&self) {
|
||||
trace::info!("Outbox stopped");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Para tareas periódicas no hace falta escribir el bucle: [Programar tareas periódicas](cron.md)
|
||||
lo resuelve con una extensión.
|
||||
|
||||
## 4. Pon componentes en todas las páginas
|
||||
|
||||
`InRegion` registra un componente una sola vez para que aparezca en todas las páginas:
|
||||
|
||||
| Variante | Dónde aparece |
|
||||
|---|---|
|
||||
| `InRegion::Content` | Región de contenido, en todas las páginas |
|
||||
| `InRegion::Global(®ion)` | La región indicada, con cualquier tema |
|
||||
| `InRegion::ForTheme(&theme, ®ion)` | La región indicada, sólo con ese tema |
|
||||
|
||||
Cada página recibe una **copia nueva** del componente. Si debe mostrarse sólo a veces (por
|
||||
ejemplo, a usuarios autenticados), haz que lo decida su `is_renderable()`.
|
||||
|
||||
## 5. Añade *middleware*
|
||||
|
||||
Las capas añadidas en `configure_middleware()` se aplican a las rutas de todas las extensiones,
|
||||
sin importar el orden. Así funciona, por ejemplo, la resolución de la sesión de usuario:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
async fn custom_header(request: web::Request, next: web::middleware::Next) -> Response {
|
||||
let mut response = next.run(request).await;
|
||||
response.headers_mut().insert("x-powered-by", web::http::HeaderValue::from_static("PageTop"));
|
||||
response
|
||||
}
|
||||
|
||||
pub struct Headers;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Headers {
|
||||
fn configure_middleware(&self, router: Router) -> Router {
|
||||
router.layer(web::middleware::from_fn(custom_header))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Para una capa que sólo afecte a tus rutas, crea un `Router` propio en `configure_router()`, aplica
|
||||
la capa sobre él y únelo con `router.merge(...)`. Compresión, límites, tiempo máximo, CORS y el
|
||||
orden de las capas, en [Añadir *middleware*](middleware.md).
|
||||
|
||||
## Comprueba
|
||||
|
||||
Declara la extensión en `dependencies()` de tu aplicación y arranca: sus rutas responden y, si su
|
||||
`initialize()` falla, la aplicación no arranca y lo explica en el terminal.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Intervenir con acciones](actions.md): cómo una extensión modifica lo que hace otra.
|
||||
- [Configurar la aplicación](configuration.md#5-ajustes-de-tu-extensión): ajustes propios de la
|
||||
extensión.
|
||||
- [Arquitectura: del arranque a la respuesta](../explanation/architecture.md).
|
||||
220
doc/v0.6/es/src/how-to/forms.md
Normal file
220
doc/v0.6/es/src/how-to/forms.md
Normal file
|
|
@ -0,0 +1,220 @@
|
|||
# Crear y procesar formularios
|
||||
|
||||
**Objetivo:** construir un formulario accesible, recibir sus datos en el servidor, validarlos y
|
||||
responder sin que una recarga lo reenvíe.
|
||||
|
||||
## 1. Construye el formulario
|
||||
|
||||
Un formulario se construye con `Form` y sus campos, que generan el HTML accesible (etiquetas,
|
||||
textos de ayuda, atributos ARIA) por ti.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
fn contact_form() -> Form {
|
||||
Form::new()
|
||||
.with_id("contact")
|
||||
.with_action("/contact")
|
||||
.with_method(form::Method::Post)
|
||||
.with_child(
|
||||
form::input::Field::text()
|
||||
.with_name("name")
|
||||
.with_label(Lc::n("Name"))
|
||||
.with_required(true),
|
||||
)
|
||||
.with_child(
|
||||
form::input::Field::email()
|
||||
.with_name("email")
|
||||
.with_label(Lc::n("Email"))
|
||||
.with_help_text(Lc::n("We will only use it to reply to you.")),
|
||||
)
|
||||
.with_child(
|
||||
form::Textarea::new()
|
||||
.with_name("message")
|
||||
.with_label(Lc::n("Message"))
|
||||
.with_rows(5),
|
||||
)
|
||||
.with_child(Button::submit(Lc::n("Send")))
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Elige los campos
|
||||
|
||||
| Campo | Constructor |
|
||||
|---|---|
|
||||
| Texto, correo, URL, teléfono, búsqueda | `form::input::Field::text()`, `email()`, `url()`, `telephone()`, `search()` |
|
||||
| Contraseña | `form::input::Field::password()` |
|
||||
| Número | `form::Number::new()` con `with_min()`, `with_max()`, `with_step()` |
|
||||
| Rango | `form::Range::new()` |
|
||||
| Área de texto | `form::Textarea::new()` |
|
||||
| Casilla o interruptor | `form::Checkbox::check()`, `form::Checkbox::switch()` |
|
||||
| Grupo de casillas | `form::check::Field` con `form::check::Item` |
|
||||
| Opciones excluyentes | `form::radio::Field` con `form::radio::Item` |
|
||||
| Lista desplegable | `form::select::Field` con `form::select::Item` |
|
||||
| Fecha, hora, fecha y hora | `form::date::Field::date()`, `time()`, `datetime()` |
|
||||
| Campo oculto | `form::Hidden::field(name, value)` |
|
||||
| Idioma, tema, zona horaria | `form::SelectLanguage`, `form::SelectTheme`, `form::SelectTimezone` |
|
||||
|
||||
Agrupa campos relacionados con `form::Fieldset`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> form::Fieldset {
|
||||
form::Fieldset::new()
|
||||
.with_legend(Lc::n("Preferences"))
|
||||
.with_child(
|
||||
form::radio::Field::new()
|
||||
.with_name("frequency")
|
||||
.with_label(Lc::n("How often do you want news?"))
|
||||
.with_item(form::radio::Item::new("weekly", Lc::n("Every week")).with_checked(true))
|
||||
.with_item(form::radio::Item::new("monthly", Lc::n("Every month"))),
|
||||
)
|
||||
.with_child(
|
||||
form::select::Field::new()
|
||||
.with_name("country")
|
||||
.with_label(Lc::n("Country"))
|
||||
.with_item(form::select::Item::new("es", Lc::n("Spain")))
|
||||
.with_item(form::select::Item::new("mx", Lc::n("Mexico")))
|
||||
.with_item(form::select::Item::new("ar", Lc::n("Argentina"))),
|
||||
)
|
||||
.with_child(form::Checkbox::switch().with_name("alerts").with_label(Lc::n("Alert me")))
|
||||
# }
|
||||
```
|
||||
|
||||
## 3. Recibe y valida los datos
|
||||
|
||||
Atiende `GET` y `POST` en la misma ruta. El *handler* del envío recibe los campos con
|
||||
`web::Form`, siempre como **último** parámetro (consume el cuerpo de la petición):
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
# fn contact_form() -> Form { Form::new() }
|
||||
pub struct Contact;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Contact {
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router.route("/contact", web::get(show).post(send))
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct ContactData {
|
||||
name: String,
|
||||
email: String,
|
||||
message: String,
|
||||
}
|
||||
|
||||
async fn show(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Contact"))
|
||||
.with_child(contact_form())
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn send(
|
||||
request: HttpRequest,
|
||||
web::Form(data): web::Form<ContactData>,
|
||||
) -> Result<Response, ErrorPage> {
|
||||
if data.message.trim().is_empty() {
|
||||
// Shows the form again with a message.
|
||||
let mut page = Page::new(request).with_child(contact_form());
|
||||
page.context()
|
||||
.push_message(MessageLevel::Error, Lc::n("Please write a message."));
|
||||
return page.render().await.map(IntoResponse::into_response);
|
||||
}
|
||||
// ... save or send `data` ...
|
||||
let cx = Context::new(request);
|
||||
Ok(Redirect::see_other(cx.route("/contact")).with_message(
|
||||
&cx,
|
||||
MessageLevel::Info,
|
||||
Lc::n("Thank you, we will reply soon."),
|
||||
))
|
||||
}
|
||||
```
|
||||
|
||||
Si el mensaje está en blanco, la página se repite con un aviso. No hace falta añadir el componente
|
||||
`Messages`: la región de contenido ya empieza por uno que muestra los avisos acumulados con
|
||||
`push_message()`.
|
||||
|
||||
Tras guardar, redirige con `see_other()` (patrón *Post/Redirect/Get*): así, si el usuario recarga
|
||||
la página, no reenvía el formulario. Para avisar del resultado en la página a la que rediriges,
|
||||
añade el mensaje a la respuesta con `with_message()`: viaja en una *cookie* de vida corta, ya
|
||||
traducido, y la página siguiente lo muestra como si se hubiera añadido con `push_message()`. Si esa
|
||||
página vuelve a redirigir, el mensaje espera a la siguiente.
|
||||
|
||||
## 4. Campos con varios valores
|
||||
|
||||
`web::Form` no admite claves repetidas (`interest=rust&interest=web`), que es lo que envían un grupo
|
||||
de casillas o una lista de selección múltiple. Para ellas, lee el cuerpo en bruto con
|
||||
`web::RawForm` y deserialízalo con [`serde_qs`](https://docs.rs/serde_qs):
|
||||
|
||||
```rust,ignore
|
||||
#[derive(Deserialize)]
|
||||
struct Interests {
|
||||
#[serde(default)]
|
||||
interest: Vec<String>,
|
||||
}
|
||||
|
||||
async fn save(request: HttpRequest, web::RawForm(body): web::RawForm) -> Response {
|
||||
let data: Interests = serde_qs::from_bytes(&body).unwrap_or(Interests { interest: vec![] });
|
||||
// ...
|
||||
# todo!()
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Fechas en el idioma del usuario
|
||||
|
||||
`form::date::Field` muestra y lee las fechas con el formato del idioma activo (`dd/mm/aaaa` en
|
||||
español). Para interpretar el texto recibido, usa los métodos del contexto:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
fn read_date(cx: &Context, text: &str) {
|
||||
match cx.parse_date(text) {
|
||||
Ok(Some(date)) => { /* a valid date: a `NaiveDate` */ }
|
||||
Ok(None) => { /* empty field */ }
|
||||
Err(_) => { /* invalid format */ }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Sin *tokens* contra CSRF
|
||||
|
||||
Los formularios no necesitan ningún campo oculto contra CSRF (*Cross-Site Request Forgery*), el
|
||||
ataque en el que otra web hace que el navegador de tus usuarios envíe peticiones a tu aplicación
|
||||
con su sesión abierta. PageTop rechaza con `403` cualquier petición que pueda cambiar algo (todos
|
||||
los métodos salvo `GET`, `HEAD` y `OPTIONS`) si el navegador indica, con las cabeceras
|
||||
`Sec-Fetch-Site` y `Origin`, que llega desde otro origen, también desde otro subdominio del mismo
|
||||
sitio. Vale igual para formularios, HTMX y `fetch`, y no afecta a `curl`, a otros servidores ni a
|
||||
las pruebas, que no envían esas cabeceras.
|
||||
|
||||
A cambio, dos reglas:
|
||||
|
||||
- **Un `GET` nunca cambia nada.** Borrar, cerrar sesión o confirmar van siempre con `POST` (o
|
||||
`PUT`, `PATCH`, `DELETE`), aunque el formulario sea sólo un botón.
|
||||
- **Otra aplicación tuya, servida desde otro origen,** que envíe formularios o peticiones a ésta
|
||||
debe figurar en `trusted_origins`:
|
||||
|
||||
```toml
|
||||
[server]
|
||||
trusted_origins = ["https://shop.example.com"]
|
||||
```
|
||||
|
||||
Ninguna protección contra CSRF resiste un fallo de XSS en la propia aplicación: por eso `html!`
|
||||
escapa siempre el texto que insertas.
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Envía el formulario vacío: el navegador lo impide, porque `name` es obligatorio.
|
||||
2. Envía un mensaje en blanco (sólo espacios): el servidor lo rechaza y el formulario vuelve con el
|
||||
aviso.
|
||||
3. Envía uno correcto: vuelves al formulario con el aviso de agradecimiento. Recarga la página: el
|
||||
aviso ya no aparece y el navegador no ofrece reenviar el formulario.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Validar un campo al vuelo](htmx-validation.md): los mismos errores, sin recargar la página.
|
||||
- [Añadir usuarios y permisos](users.md): formularios que sólo ven algunos usuarios.
|
||||
233
doc/v0.6/es/src/how-to/html.md
Normal file
233
doc/v0.6/es/src/how-to/html.md
Normal file
|
|
@ -0,0 +1,233 @@
|
|||
# Escribir HTML con `html!`
|
||||
|
||||
**Objetivo:** escribir marcado con la macro `html!`: elementos, valores de Rust, atributos
|
||||
condicionales, bucles y fragmentos reutilizables, todo comprobado al compilar.
|
||||
|
||||
PageTop escribe HTML con la macro `html!`, basada en [Maud](https://maud.lambda.xyz). Es Rust: si
|
||||
cierras mal una etiqueta o te equivocas con una variable, **no compila**.
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
let markup = html! {
|
||||
article class="post" {
|
||||
h2 { "Title" }
|
||||
p { "A paragraph with " strong { "bold" } " text." }
|
||||
img src="/photo.jpg" alt="A photo";
|
||||
}
|
||||
};
|
||||
assert_eq!(
|
||||
markup.into_string(),
|
||||
r#"<article class="post"><h2>Title</h2><p>A paragraph with <strong>bold</strong> text.</p><img src="/photo.jpg" alt="A photo"></article>"#
|
||||
);
|
||||
```
|
||||
|
||||
Las reglas básicas:
|
||||
|
||||
- Un elemento con contenido lleva llaves: `p { ... }`.
|
||||
- Un elemento vacío termina en punto y coma: `br;`, `img src="...";`.
|
||||
- El texto va entre comillas y los atributos se escriben como en HTML.
|
||||
- Los comentarios son los de Rust (`// ...`) y no llegan al HTML.
|
||||
|
||||
No hace falta escribir el `<!DOCTYPE>`, el `<head>` ni el `<body>`: los pone `Page` (ve
|
||||
[Construir páginas](pages.md)). Con `html!` escribes sólo el contenido.
|
||||
|
||||
## Insertar valores de Rust
|
||||
|
||||
Cualquier expresión entre paréntesis se inserta en el HTML, **escapada**:
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
let name = "<Ana>";
|
||||
let total = 3;
|
||||
let markup = html! { p { "Hello, " (name) ". You have " (total) " notices." } };
|
||||
assert_eq!(markup.into_string(), "<p>Hello, <Ana>. You have 3 notices.</p>");
|
||||
```
|
||||
|
||||
El escape es lo que te protege de la inyección de código (XSS): si un usuario escribe
|
||||
`<script>` en un formulario, la página muestra el texto, no lo ejecuta.
|
||||
|
||||
Si necesitas insertar HTML que ya es seguro, envuélvelo en `PreEscaped`:
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
let fragment = "<em>already escaped</em>";
|
||||
let markup = html! { p { (PreEscaped(fragment)) } };
|
||||
assert_eq!(markup.into_string(), "<p><em>already escaped</em></p>");
|
||||
```
|
||||
|
||||
Lo que pongas en `PreEscaped` llega al navegador tal cual. Úsalo sólo con contenido de confianza,
|
||||
nunca con texto que venga de un usuario.
|
||||
|
||||
## Atributos dinámicos
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
let url = "/profile";
|
||||
let title: Option<&str> = None;
|
||||
let active = true;
|
||||
let markup = html! {
|
||||
a href=(url) title=[title] { "Profile" }
|
||||
input type="checkbox" checked[active];
|
||||
li class="item" .active[active] { "Home" }
|
||||
};
|
||||
assert_eq!(
|
||||
markup.into_string(),
|
||||
r#"<a href="/profile">Profile</a><input type="checkbox" checked><li class="item active">Home</li>"#
|
||||
);
|
||||
```
|
||||
|
||||
- `attr=(expr)` fija el valor.
|
||||
- `attr=[option]` sólo escribe el atributo si la opción es `Some`.
|
||||
- `attr[condition]` escribe un atributo booleano si la condición es cierta.
|
||||
- `.class[condition]` añade una clase si la condición es cierta. Se combina con `class="..."`:
|
||||
`html!` junta las fijas y las condicionadas en un único atributo `class`.
|
||||
- Los atributos con guiones se escriben tal cual: `hx-get="/time"`, `aria-label="Close"`,
|
||||
`data-id=(id)`.
|
||||
|
||||
## Control de flujo
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
let tasks = ["Read", "Code", "Rest"];
|
||||
let user: Option<&str> = Some("Ana");
|
||||
let markup = html! {
|
||||
@if let Some(name) = user {
|
||||
p { "Signed in as " (name) }
|
||||
} @else {
|
||||
p { "Not signed in" }
|
||||
}
|
||||
ul {
|
||||
@for (i, task) in tasks.iter().enumerate() {
|
||||
@let number = i + 1;
|
||||
li { (number) ". " (task) }
|
||||
}
|
||||
}
|
||||
};
|
||||
assert!(markup.into_string().starts_with("<p>Signed in as Ana</p><ul><li>1. Read</li>"));
|
||||
```
|
||||
|
||||
`@match` elige el marcado según un valor, con los mismos patrones que un `match` de Rust:
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
enum Plot {
|
||||
Free,
|
||||
Taken(&'static str),
|
||||
}
|
||||
|
||||
let plots = [Plot::Taken("Ana"), Plot::Free];
|
||||
let markup = html! {
|
||||
@for plot in &plots {
|
||||
@match plot {
|
||||
Plot::Free => span class="free" { "Free" },
|
||||
Plot::Taken(holder) => span { "Taken by " (holder) },
|
||||
}
|
||||
}
|
||||
};
|
||||
assert_eq!(markup.into_string(), r#"<span>Taken by Ana</span><span class="free">Free</span>"#);
|
||||
```
|
||||
|
||||
También existe `@while`.
|
||||
|
||||
## Reutilizar fragmentos
|
||||
|
||||
Un fragmento que se repite se convierte en una función que devuelve `Markup`, y se inserta como
|
||||
cualquier otro valor:
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
fn plot_card(name: &str, holder: &str) -> Markup {
|
||||
html! {
|
||||
article class="plot-card" {
|
||||
h3 { (name) }
|
||||
p { "Holder: " (holder) }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let markup = html! {
|
||||
(plot_card("A1", "Ana"))
|
||||
(plot_card("B2", "Luke"))
|
||||
};
|
||||
assert_eq!(
|
||||
markup.into_string(),
|
||||
concat!(
|
||||
r#"<article class="plot-card"><h3>A1</h3><p>Holder: Ana</p></article>"#,
|
||||
r#"<article class="plot-card"><h3>B2</h3><p>Holder: Luke</p></article>"#,
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
Es lo que en un motor de plantillas haría un *include*, pero con parámetros tipados: si te olvidas
|
||||
de uno, no compila. Y no necesitas una plantilla base de la que heredar: la estructura común de
|
||||
todas las páginas (cabecera, menú, pie) la ponen el tema y sus regiones.
|
||||
|
||||
## Insertar tus propios tipos
|
||||
|
||||
Cualquier tipo que implemente `Display` se inserta directamente, escapado:
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
use std::fmt;
|
||||
|
||||
struct Holder {
|
||||
name: String,
|
||||
}
|
||||
|
||||
impl fmt::Display for Holder {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
write!(f, "{} (gardener)", self.name)
|
||||
}
|
||||
}
|
||||
|
||||
let holder = Holder { name: "Ana".to_string() };
|
||||
let markup = html! { p { (holder) } };
|
||||
assert_eq!(markup.into_string(), "<p>Ana (gardener)</p>");
|
||||
```
|
||||
|
||||
Para que un tipo genere su propio marcado, implementa `Render`:
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
struct Area(u32);
|
||||
|
||||
impl Render for Area {
|
||||
fn render(&self) -> Markup {
|
||||
html! { span class="area" { (self.0) " m²" } }
|
||||
}
|
||||
}
|
||||
|
||||
let markup = html! { p { "Size: " (Area(25)) } };
|
||||
assert_eq!(markup.into_string(), r#"<p>Size: <span class="area">25 m²</span></p>"#);
|
||||
```
|
||||
|
||||
Una función o un tipo con `Render` bastan para piezas pequeñas sin estado. Cuando la pieza necesita
|
||||
el idioma, la petición o que un tema pueda cambiarla, conviértela en un
|
||||
[componente](custom-components.md).
|
||||
|
||||
## `Html`: el componente comodín
|
||||
|
||||
En una página no se inserta `Markup` directamente, sino **componentes**. El más sencillo es
|
||||
`Html`, que envuelve un cierre con `html!`. El cierre recibe el contexto de renderizado (`cx`), con
|
||||
el idioma, el tema o la petición actuales:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_child(Html::with(|cx| {
|
||||
let greeting = Lc::n("Welcome");
|
||||
html! { h1 { (greeting.using(cx)) } }
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
Úsalo para marcado puntual. Cuando un fragmento se repite o tiene entidad propia, conviértelo en
|
||||
un [componente](custom-components.md).
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Usar componentes](components.md): antes de escribir HTML, mira si ya existe un componente.
|
||||
- [Crear un componente](custom-components.md).
|
||||
235
doc/v0.6/es/src/how-to/htmx-delete.md
Normal file
235
doc/v0.6/es/src/how-to/htmx-delete.md
Normal file
|
|
@ -0,0 +1,235 @@
|
|||
# Borrar con confirmación
|
||||
|
||||
**Objetivo:** un botón en cada fila de una tabla que pide confirmación, borra en el servidor y
|
||||
retira la fila con un fundido, actualizando a la vez un contador que está fuera de la tabla.
|
||||
|
||||
Partimos de una aplicación con [HTMX añadido](htmx-setup.md) y de una tabla como las de [Mostrar
|
||||
tablas ordenables y paginadas](tables.md).
|
||||
|
||||
## 1. Un botón de borrar en cada fila
|
||||
|
||||
Las piezas de `Table` (filas, celdas, cabeceras) aceptan atributos con `with_prop()`, igual que los
|
||||
componentes. El botón de cada fila lleva cuatro:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
struct Plot {
|
||||
id: u32,
|
||||
name: &'static str,
|
||||
holder: &'static str,
|
||||
}
|
||||
|
||||
fn plot_row(plot: &Plot) -> table::Row {
|
||||
let delete = Button::plain(Lc::n("Delete"))
|
||||
.with_style(button::Style::Outline(Intent::Severe))
|
||||
.with_prop(PropsOp::set(hx::DELETE, util::join!("/plots/", plot.id.to_string())))
|
||||
.with_prop(PropsOp::set(hx::CONFIRM, "Delete this plot?"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "closest tr"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, "outerHTML swap:300ms"));
|
||||
table::Row::new()
|
||||
.with_cell(plot.name)
|
||||
.with_cell(plot.holder)
|
||||
.with_cell(delete)
|
||||
}
|
||||
```
|
||||
|
||||
- `hx-confirm` muestra el diálogo de confirmación del navegador. Si el usuario cancela, no se envía
|
||||
nada.
|
||||
- `hx-target="closest tr"` apunta a la fila que contiene el botón, sin necesidad de darle un `id`.
|
||||
- `swap:300ms` espera 300 ms antes de sustituir la fila. Es el tiempo del fundido del paso 3.
|
||||
|
||||
## 2. La ruta devuelve un fragmento vacío
|
||||
|
||||
Al sustituir la fila (`outerHTML`) por una respuesta vacía, la fila desaparece. Y el contador de
|
||||
parcelas, que está fuera de la tabla, viaja en la misma respuesta **fuera de banda**:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
# struct Plot { id: u32 }
|
||||
# fn plots() -> std::sync::MutexGuard<'static, Vec<Plot>> { todo!() }
|
||||
|
||||
fn count_update(count: usize) -> Markup {
|
||||
html! { span id="plot-count" hx-swap-oob="true" { (count) } }
|
||||
}
|
||||
|
||||
async fn delete(web::Path(id): web::Path<u32>) -> HtmxResponse {
|
||||
let mut plots = plots();
|
||||
plots.retain(|plot| plot.id != id);
|
||||
HtmxResponse::empty().oob(count_update(plots.len()))
|
||||
}
|
||||
```
|
||||
|
||||
## 3. El fundido
|
||||
|
||||
Durante esos 300 ms, HTMX pone la clase `htmx-swapping` en la fila. Con una regla CSS en la hoja de
|
||||
estilos de tu aplicación, la fila se desvanece antes de irse:
|
||||
|
||||
```css
|
||||
tr.htmx-swapping {
|
||||
opacity: 0;
|
||||
transition: opacity 300ms ease-out;
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Cuando no queda nada
|
||||
|
||||
Al borrar la última fila, lo correcto es mostrar la tabla vacía con su mensaje («No plots left»),
|
||||
no una tabla sin filas. La ruta puede **cambiar el destino** de su respuesta: en lugar de la fila,
|
||||
sustituye el contenedor de la tabla entera.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_htmx::prelude::*;
|
||||
# struct Plot { id: u32 }
|
||||
# fn plots() -> std::sync::MutexGuard<'static, Vec<Plot>> { todo!() }
|
||||
# fn count_update(_: usize) -> Markup { html! {} }
|
||||
# fn plots_table(_: &[Plot]) -> Container { Container::new() }
|
||||
async fn delete(request: HttpRequest, web::Path(id): web::Path<u32>) -> HtmxResponse {
|
||||
let (empty_table, count) = {
|
||||
let mut plots = plots();
|
||||
plots.retain(|plot| plot.id != id);
|
||||
(plots.is_empty().then(|| plots_table(&plots)), count_update(plots.len()))
|
||||
};
|
||||
if let Some(mut table) = empty_table {
|
||||
let table = table.render(&mut Context::new(request)).await;
|
||||
return HtmxResponse::new(table)
|
||||
.retarget("#plots")
|
||||
.reswap(hx::swap::OUTER_HTML)
|
||||
.oob(count);
|
||||
}
|
||||
HtmxResponse::empty().oob(count)
|
||||
}
|
||||
```
|
||||
|
||||
`plots_table()` construye la tabla dentro de un `Container` con `id="plots"`, que es el nuevo
|
||||
destino (lo tienes en el ejemplo completo). El bloque `{ ... }` suelta el `Mutex` **antes** del
|
||||
`.await`: un candado de la biblioteca estándar no puede quedar abierto mientras la tarea espera.
|
||||
|
||||
`retarget()` y `reswap()` envían las cabeceras `HX-Retarget` y `HX-Reswap`, que mandan sobre lo que
|
||||
dijeran los atributos del botón.
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
use std::sync::{LazyLock, Mutex, MutexGuard};
|
||||
|
||||
struct Plot {
|
||||
id: u32,
|
||||
name: &'static str,
|
||||
holder: &'static str,
|
||||
}
|
||||
|
||||
static PLOTS: LazyLock<Mutex<Vec<Plot>>> = LazyLock::new(|| {
|
||||
Mutex::new(vec![
|
||||
Plot { id: 1, name: "A1", holder: "Ana" },
|
||||
Plot { id: 2, name: "A2", holder: "Luke" },
|
||||
Plot { id: 3, name: "B1", holder: "Marta" },
|
||||
])
|
||||
});
|
||||
|
||||
fn plots() -> MutexGuard<'static, Vec<Plot>> {
|
||||
PLOTS.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
|
||||
}
|
||||
|
||||
struct Allotments;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Allotments {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(home))
|
||||
.route("/plots/{id}", web::delete(delete))
|
||||
}
|
||||
}
|
||||
|
||||
fn plot_row(plot: &Plot) -> table::Row {
|
||||
let delete = Button::plain(Lc::n("Delete"))
|
||||
.with_style(button::Style::Outline(Intent::Severe))
|
||||
.with_prop(PropsOp::set(hx::DELETE, util::join!("/plots/", plot.id.to_string())))
|
||||
.with_prop(PropsOp::set(hx::CONFIRM, "Delete this plot?"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "closest tr"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, "outerHTML swap:300ms"));
|
||||
table::Row::new()
|
||||
.with_cell(plot.name)
|
||||
.with_cell(plot.holder)
|
||||
.with_cell(delete)
|
||||
}
|
||||
|
||||
fn plots_table(plots: &[Plot]) -> Container {
|
||||
let mut table = Table::new()
|
||||
.with_column(table::Column::new(Lc::n("Plot")))
|
||||
.with_column(table::Column::new(Lc::n("Holder")))
|
||||
.with_column(table::Column::new(Lc::none()))
|
||||
.with_empty(Lc::n("No plots left."));
|
||||
for plot in plots {
|
||||
table = table.with_row(plot_row(plot));
|
||||
}
|
||||
Container::new().with_id("plots").with_child(table)
|
||||
}
|
||||
|
||||
fn count_update(count: usize) -> Markup {
|
||||
html! { span id="plot-count" hx-swap-oob="true" { (count) } }
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
let (table, count) = {
|
||||
let plots = plots();
|
||||
(plots_table(&plots), plots.len())
|
||||
};
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Allotments"))
|
||||
.with_child(Html::with(move |_| html! {
|
||||
style { "tr.htmx-swapping { opacity: 0; transition: opacity 300ms ease-out; }" }
|
||||
h1 { "Allotments (" span id="plot-count" { (count) } ")" }
|
||||
}))
|
||||
.with_child(table)
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn delete(request: HttpRequest, web::Path(id): web::Path<u32>) -> HtmxResponse {
|
||||
let (empty_table, count) = {
|
||||
let mut plots = plots();
|
||||
plots.retain(|plot| plot.id != id);
|
||||
(plots.is_empty().then(|| plots_table(&plots)), count_update(plots.len()))
|
||||
};
|
||||
if let Some(mut table) = empty_table {
|
||||
let table = table.render(&mut Context::new(request)).await;
|
||||
return HtmxResponse::new(table)
|
||||
.retarget("#plots")
|
||||
.reswap(hx::swap::OUTER_HTML)
|
||||
.oob(count);
|
||||
}
|
||||
HtmxResponse::empty().oob(count)
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Allotments).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
El ejemplo pone la regla CSS en un `<style>` para que quepa en un archivo; en una aplicación, va en
|
||||
su [hoja de estilos](assets.md).
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Pulsa *Delete* en una fila y acepta: la fila se desvanece y el contador del título baja.
|
||||
2. Pulsa *Delete* y cancela: no pasa nada, y en la pestaña *Red* no hay petición.
|
||||
3. Borra todas: al irse la última, aparece «No plots left.» y el contador marca 0.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Ordenar y paginar sin recargar](htmx-tables.md).
|
||||
- [Dirigir al navegador desde el servidor](htmx-responses.md): todas las cabeceras que puede enviar
|
||||
una respuesta.
|
||||
273
doc/v0.6/es/src/how-to/htmx-edit.md
Normal file
273
doc/v0.6/es/src/how-to/htmx-edit.md
Normal file
|
|
@ -0,0 +1,273 @@
|
|||
# Editar en línea
|
||||
|
||||
**Objetivo:** que un bloque de datos se convierta en un formulario al pulsar *Edit*, y vuelva a ser
|
||||
un bloque al guardar o cancelar, sin salir de la página.
|
||||
|
||||
Partimos de una aplicación con [HTMX añadido](htmx-setup.md). El tutorial [Tareas del huerto con
|
||||
HTMX](../tutorials/htmx-tasks.md) hace lo mismo con elementos de una lista; aquí se hace con
|
||||
componentes: un `Block` con un `Form` dentro.
|
||||
|
||||
## 1. Dos versiones del mismo bloque
|
||||
|
||||
La idea es tener dos funciones que construyen **el mismo bloque** (mismo `id`) en sus dos estados.
|
||||
Los dos llevan `hx-target="this"` y `hx-swap="outerHTML"`, que heredan sus botones: cualquier
|
||||
petición que salga de dentro sustituye el bloque entero.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
#[derive(Clone)]
|
||||
struct Contact {
|
||||
name: String,
|
||||
phone: String,
|
||||
}
|
||||
|
||||
fn contact_block() -> Block {
|
||||
Block::new()
|
||||
.with_id("contact")
|
||||
.with_title(Lc::n("Garden coordinator"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "this"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::OUTER_HTML))
|
||||
}
|
||||
|
||||
fn view_block(contact: &Contact) -> Block {
|
||||
let contact = contact.clone();
|
||||
contact_block()
|
||||
.with_child(Html::with(move |_| html! {
|
||||
p { (contact.name) }
|
||||
p { (contact.phone) }
|
||||
}))
|
||||
.with_child(Button::plain(Lc::n("Edit")).with_prop(PropsOp::set(hx::GET, "/contact/edit")))
|
||||
}
|
||||
|
||||
fn edit_block(contact: &Contact) -> Block {
|
||||
contact_block().with_child(Messages::new()).with_child(
|
||||
Form::new()
|
||||
.with_prop(PropsOp::set(hx::PUT, "/contact"))
|
||||
.with_child(
|
||||
form::input::Field::text()
|
||||
.with_name("name")
|
||||
.with_value(&contact.name)
|
||||
.with_label(Lc::n("Name"))
|
||||
.with_required(true),
|
||||
)
|
||||
.with_child(
|
||||
form::input::Field::telephone()
|
||||
.with_name("phone")
|
||||
.with_value(&contact.phone)
|
||||
.with_label(Lc::n("Phone")),
|
||||
)
|
||||
.with_child(Button::submit(Lc::n("Save")))
|
||||
.with_child(Button::plain(Lc::n("Cancel")).with_prop(PropsOp::set(hx::GET, "/contact"))),
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
El formulario no necesita `hx-target` propio: lo hereda del bloque. *Cancel* es un botón normal
|
||||
(`type="button"`), así que no envía el formulario; sólo pide la vista.
|
||||
|
||||
## 2. Tres rutas pequeñas
|
||||
|
||||
| Ruta | Devuelve |
|
||||
|---|---|
|
||||
| `GET /contact/edit` | El bloque con el formulario |
|
||||
| `GET /contact` | El bloque en modo vista (para *Cancel*) |
|
||||
| `PUT /contact` | El bloque en modo vista con los datos nuevos, o el formulario con un error |
|
||||
|
||||
Las tres renderizan un `Block` fuera de una página, con un `Context` creado a partir de la
|
||||
petición. Una función común lo hace, y de paso añade el error si lo hay:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_htmx::prelude::*;
|
||||
async fn fragment(request: HttpRequest, mut block: Block, error: Option<Lc>) -> HtmxResponse {
|
||||
let mut cx = Context::new(request);
|
||||
if let Some(error) = error {
|
||||
cx.push_message(MessageLevel::Error, error);
|
||||
}
|
||||
HtmxResponse::new(block.render(&mut cx).await)
|
||||
}
|
||||
```
|
||||
|
||||
Guardar valida antes de cambiar nada. Si algo falla, el usuario recibe su formulario **con lo que
|
||||
escribió** y el motivo:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_htmx::prelude::*;
|
||||
# use serde::Deserialize;
|
||||
# use std::sync::Mutex;
|
||||
# #[derive(Clone)]
|
||||
# struct Contact { name: String, phone: String }
|
||||
# static CONTACT: Mutex<Option<Contact>> = Mutex::new(None);
|
||||
# fn stored() -> std::sync::MutexGuard<'static, Option<Contact>> { CONTACT.lock().unwrap() }
|
||||
# fn view_block(_: &Contact) -> Block { Block::new() }
|
||||
# fn edit_block(_: &Contact) -> Block { Block::new() }
|
||||
# async fn fragment(_: HttpRequest, _: Block, _: Option<Lc>) -> HtmxResponse { todo!() }
|
||||
#[derive(Deserialize)]
|
||||
struct ContactForm {
|
||||
name: String,
|
||||
phone: String,
|
||||
}
|
||||
|
||||
async fn save(request: HttpRequest, web::Form(form): web::Form<ContactForm>) -> HtmxResponse {
|
||||
let contact = Contact {
|
||||
name: form.name.trim().to_string(),
|
||||
phone: form.phone.trim().to_string(),
|
||||
};
|
||||
if contact.name.is_empty() {
|
||||
let error = Lc::n("The coordinator needs a name.");
|
||||
return fragment(request, edit_block(&contact), Some(error)).await;
|
||||
}
|
||||
*stored() = Some(contact.clone());
|
||||
fragment(request, view_block(&contact), None).await
|
||||
}
|
||||
```
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
use std::sync::{Mutex, MutexGuard};
|
||||
|
||||
#[derive(Clone)]
|
||||
struct Contact {
|
||||
name: String,
|
||||
phone: String,
|
||||
}
|
||||
|
||||
static CONTACT: Mutex<Option<Contact>> = Mutex::new(None);
|
||||
|
||||
fn stored() -> MutexGuard<'static, Option<Contact>> {
|
||||
CONTACT.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
|
||||
}
|
||||
|
||||
fn current_contact() -> Contact {
|
||||
stored().clone().unwrap_or_else(|| Contact {
|
||||
name: "Ana Pérez".into(),
|
||||
phone: "+34 600 000 000".into(),
|
||||
})
|
||||
}
|
||||
|
||||
struct Coordinator;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Coordinator {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(home))
|
||||
.route("/contact", web::get(show).put(save))
|
||||
.route("/contact/edit", web::get(edit))
|
||||
}
|
||||
}
|
||||
|
||||
fn contact_block() -> Block {
|
||||
Block::new()
|
||||
.with_id("contact")
|
||||
.with_title(Lc::n("Garden coordinator"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "this"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::OUTER_HTML))
|
||||
}
|
||||
|
||||
fn view_block(contact: &Contact) -> Block {
|
||||
let contact = contact.clone();
|
||||
contact_block()
|
||||
.with_child(Html::with(move |_| html! {
|
||||
p { (contact.name) }
|
||||
p { (contact.phone) }
|
||||
}))
|
||||
.with_child(Button::plain(Lc::n("Edit")).with_prop(PropsOp::set(hx::GET, "/contact/edit")))
|
||||
}
|
||||
|
||||
fn edit_block(contact: &Contact) -> Block {
|
||||
contact_block().with_child(Messages::new()).with_child(
|
||||
Form::new()
|
||||
.with_prop(PropsOp::set(hx::PUT, "/contact"))
|
||||
.with_child(
|
||||
form::input::Field::text()
|
||||
.with_name("name")
|
||||
.with_value(&contact.name)
|
||||
.with_label(Lc::n("Name"))
|
||||
.with_required(true),
|
||||
)
|
||||
.with_child(
|
||||
form::input::Field::telephone()
|
||||
.with_name("phone")
|
||||
.with_value(&contact.phone)
|
||||
.with_label(Lc::n("Phone")),
|
||||
)
|
||||
.with_child(Button::submit(Lc::n("Save")))
|
||||
.with_child(Button::plain(Lc::n("Cancel")).with_prop(PropsOp::set(hx::GET, "/contact"))),
|
||||
)
|
||||
}
|
||||
|
||||
async fn fragment(request: HttpRequest, mut block: Block, error: Option<Lc>) -> HtmxResponse {
|
||||
let mut cx = Context::new(request);
|
||||
if let Some(error) = error {
|
||||
cx.push_message(MessageLevel::Error, error);
|
||||
}
|
||||
HtmxResponse::new(block.render(&mut cx).await)
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Our garden"))
|
||||
.with_child(view_block(¤t_contact()))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn show(request: HttpRequest) -> HtmxResponse {
|
||||
fragment(request, view_block(¤t_contact()), None).await
|
||||
}
|
||||
|
||||
async fn edit(request: HttpRequest) -> HtmxResponse {
|
||||
fragment(request, edit_block(¤t_contact()), None).await
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct ContactForm {
|
||||
name: String,
|
||||
phone: String,
|
||||
}
|
||||
|
||||
async fn save(request: HttpRequest, web::Form(form): web::Form<ContactForm>) -> HtmxResponse {
|
||||
let contact = Contact {
|
||||
name: form.name.trim().to_string(),
|
||||
phone: form.phone.trim().to_string(),
|
||||
};
|
||||
if contact.name.is_empty() {
|
||||
let error = Lc::n("The coordinator needs a name.");
|
||||
return fragment(request, edit_block(&contact), Some(error)).await;
|
||||
}
|
||||
*stored() = Some(contact.clone());
|
||||
fragment(request, view_block(&contact), None).await
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Coordinator).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Pulsa *Edit*: el bloque se convierte en un formulario con los datos actuales.
|
||||
2. Pulsa *Cancel*: vuelve la vista, sin cambios.
|
||||
3. Borra el nombre (con espacios, para que el navegador no lo impida) y guarda: el formulario
|
||||
vuelve con el aviso y con el teléfono que habías escrito.
|
||||
4. Escribe otro nombre y guarda: la vista muestra el nuevo. Recarga la página: el cambio se
|
||||
mantiene.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Borrar con confirmación](htmx-delete.md).
|
||||
- [Validar un campo al vuelo](htmx-validation.md), para avisar antes de guardar.
|
||||
157
doc/v0.6/es/src/how-to/htmx-infinite.md
Normal file
157
doc/v0.6/es/src/how-to/htmx-infinite.md
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
# Cargar más al hacer *scroll*
|
||||
|
||||
**Objetivo:** una lista larga que carga los siguientes elementos al pulsar «Load more» o, mejor
|
||||
aún, sola, cuando el usuario llega al final.
|
||||
|
||||
Partimos de una aplicación con [HTMX añadido](htmx-setup.md).
|
||||
|
||||
## 1. Un lote de elementos y un testigo
|
||||
|
||||
La ruta devuelve un **lote** de elementos y, si quedan más, un último elemento especial: el
|
||||
**testigo**, que sabe pedir el lote siguiente y ocupa su lugar.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
const PER_PAGE: usize = 10;
|
||||
const TOTAL: usize = 35;
|
||||
|
||||
fn entries(page: usize) -> Markup {
|
||||
let start = (page - 1) * PER_PAGE;
|
||||
let end = (start + PER_PAGE).min(TOTAL);
|
||||
let next = util::join!("/diary/entries?page=", (page + 1).to_string());
|
||||
html! {
|
||||
@for day in start + 1..=end {
|
||||
li { "Day " (day) ": the garden is growing." }
|
||||
}
|
||||
@if end < TOTAL {
|
||||
li {
|
||||
button hx-get=(next) hx-target="closest li" hx-swap="outerHTML" { "Load more" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Al pulsar el botón, la respuesta (diez elementos y un testigo nuevo) **sustituye al testigo**: la
|
||||
lista crece por abajo y el botón baja con ella. Cuando no quedan elementos, el último lote no trae
|
||||
testigo y la carga termina sola.
|
||||
|
||||
## 2. Sin botón: al llegar al final
|
||||
|
||||
Para cargar sin que el usuario pulse nada, el testigo se dispara con `revealed`, que ocurre cuando
|
||||
el elemento entra en la pantalla:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f(next: String) -> Markup {
|
||||
html! {
|
||||
li hx-get=(next) hx-trigger="revealed" hx-swap="outerHTML" { "Loading more..." }
|
||||
}
|
||||
# }
|
||||
```
|
||||
|
||||
Es el mismo patrón con otro disparador. Si la lista está dentro de un contenedor con su propio
|
||||
*scroll* (`overflow: auto`), usa `hx-trigger="intersect once"`, que funciona con cualquier
|
||||
contenedor.
|
||||
|
||||
## 3. La página y la ruta del lote
|
||||
|
||||
La página pinta el primer lote dentro de la lista; la ruta del lote devuelve sólo los `<li>`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn entries(_: usize) -> Markup { html! {} }
|
||||
use serde::Deserialize;
|
||||
|
||||
async fn diary(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Garden diary"))
|
||||
.with_child(Html::with(|_| html! { ul id="diary" { (entries(1)) } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct Batch {
|
||||
page: usize,
|
||||
}
|
||||
|
||||
async fn more_entries(web::Query(batch): web::Query<Batch>) -> Markup {
|
||||
entries(batch.page.max(1))
|
||||
}
|
||||
```
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
const PER_PAGE: usize = 10;
|
||||
const TOTAL: usize = 35;
|
||||
|
||||
struct Diary;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Diary {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(diary))
|
||||
.route("/diary/entries", web::get(more_entries))
|
||||
}
|
||||
}
|
||||
|
||||
fn entries(page: usize) -> Markup {
|
||||
let start = (page - 1) * PER_PAGE;
|
||||
let end = (start + PER_PAGE).min(TOTAL);
|
||||
let next = util::join!("/diary/entries?page=", (page + 1).to_string());
|
||||
html! {
|
||||
@for day in start + 1..=end {
|
||||
li { "Day " (day) ": the garden is growing." }
|
||||
}
|
||||
@if end < TOTAL {
|
||||
li hx-get=(next) hx-trigger="revealed" hx-swap="outerHTML" { "Loading more..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async fn diary(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Garden diary"))
|
||||
.with_child(Html::with(|_| html! { ul id="diary" { (entries(1)) } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct Batch {
|
||||
page: usize,
|
||||
}
|
||||
|
||||
async fn more_entries(web::Query(batch): web::Query<Batch>) -> Markup {
|
||||
entries(batch.page.max(1))
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Diary).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Abre la página y baja: cada vez que el testigo «Loading more...» asoma por abajo, llegan diez
|
||||
días más. Si la ventana es alta y el testigo ya se ve al cargar, el segundo lote llega sin
|
||||
esperar: está a la vista.
|
||||
2. Sigue bajando hasta el día 35: el testigo ya no aparece.
|
||||
3. En la pestaña *Red* hay tres peticiones a `/diary/entries`, una por lote.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Ordenar y paginar sin recargar](htmx-tables.md): cuando el usuario necesita saltar a una página
|
||||
concreta, un paginador es mejor opción.
|
||||
- [Actualizar periódicamente](htmx-polling.md).
|
||||
168
doc/v0.6/es/src/how-to/htmx-load.md
Normal file
168
doc/v0.6/es/src/how-to/htmx-load.md
Normal file
|
|
@ -0,0 +1,168 @@
|
|||
# Cargar contenido bajo demanda
|
||||
|
||||
**Objetivo:** que una parte de la página se cargue después que el resto: cuando el usuario la pida,
|
||||
en cuanto la página esté lista o cuando se haga visible. La página aparece antes, y lo costoso
|
||||
llega por su cuenta.
|
||||
|
||||
Partimos de una aplicación con [HTMX añadido](htmx-setup.md).
|
||||
|
||||
## 1. Al pulsar
|
||||
|
||||
El caso básico: un botón trae el contenido y lo pone en su sitio.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Html {
|
||||
Html::with(|_| html! {
|
||||
button hx-get="/forecast" hx-target="#forecast" { "Show the forecast" }
|
||||
div id="forecast" {}
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
Para que el botón desaparezca y su lugar lo ocupe el contenido, apunta al propio botón y sustitúyelo
|
||||
entero:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Html {
|
||||
Html::with(|_| html! {
|
||||
button hx-get="/forecast" hx-swap="outerHTML" { "Show the forecast" }
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
## 2. En cuanto se carga la página
|
||||
|
||||
Con `hx-trigger="load"`, el elemento pide su contenido nada más aparecer. Mientras llega, muestra
|
||||
lo que tenga dentro:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Html {
|
||||
Html::with(|_| html! {
|
||||
div hx-get="/forecast" hx-trigger="load" hx-swap="outerHTML" {
|
||||
p { "Loading the forecast..." }
|
||||
}
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
Úsalo para lo que tarda (un servicio externo, una consulta pesada): la página se sirve al momento y
|
||||
ese bloque se completa después.
|
||||
|
||||
## 3. Cuando se hace visible
|
||||
|
||||
Con `hx-trigger="revealed"`, la petición espera a que el elemento entre en la pantalla. Ideal para
|
||||
lo que queda al final de una página larga, como los comentarios:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Html {
|
||||
Html::with(|_| html! {
|
||||
section hx-get="/comments" hx-trigger="revealed" hx-swap="outerHTML" {
|
||||
p { "Comments will load when you get here." }
|
||||
}
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
Si el usuario nunca baja hasta ahí, la petición no se hace.
|
||||
|
||||
## 4. Muestra que está cargando
|
||||
|
||||
Mientras dura una petición, HTMX añade la clase `htmx-request` al elemento que la hizo. Los
|
||||
elementos con la clase `htmx-indicator` están ocultos y se muestran sólo durante la petición del
|
||||
elemento que los contiene, o de quien los señale con `hx-indicator`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Html {
|
||||
Html::with(|_| html! {
|
||||
button hx-get="/forecast" hx-target="#forecast" hx-indicator="#spinner" {
|
||||
"Show the forecast"
|
||||
}
|
||||
span id="spinner" class="htmx-indicator" { " Loading..." }
|
||||
div id="forecast" {}
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
HTMX trae los estilos de `htmx-indicator`, así que funciona sin escribir CSS.
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
Una página con las tres formas, sobre las mismas dos rutas:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(home))
|
||||
.route("/forecast", web::get(forecast))
|
||||
.route("/comments", web::get(comments))
|
||||
}
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("The garden today"))
|
||||
.with_child(Html::with(|_| html! {
|
||||
h1 { "The garden today" }
|
||||
|
||||
h2 { "Forecast" }
|
||||
button hx-get="/forecast" hx-swap="outerHTML" { "Show the forecast" }
|
||||
|
||||
h2 { "Forecast, on load" }
|
||||
div hx-get="/forecast" hx-trigger="load" hx-swap="outerHTML" {
|
||||
p { "Loading the forecast..." }
|
||||
}
|
||||
|
||||
h2 { "Comments" }
|
||||
div style="height: 150vh" { p { "Scroll down..." } }
|
||||
section hx-get="/comments" hx-trigger="revealed" hx-swap="outerHTML" {
|
||||
p { "Comments will load when you get here." }
|
||||
}
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn forecast() -> Markup {
|
||||
html! { p class="forecast" { "Sunny, 24 °C. Water in the evening." } }
|
||||
}
|
||||
|
||||
async fn comments() -> Markup {
|
||||
html! {
|
||||
ul class="comments" {
|
||||
li { "Ana: the lettuces are ready." }
|
||||
li { "Luke: who has the hose key?" }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Garden).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Al abrir la página, el segundo bloque ya muestra la previsión: se pidió nada más cargarse.
|
||||
2. El botón del primero se sustituye por la previsión al pulsarlo.
|
||||
3. En la pestaña *Red*, `/comments` no aparece hasta que bajas al final de la página.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Cargar más al hacer *scroll*](htmx-infinite.md): `revealed` aplicado a listas largas.
|
||||
- [Actualizar periódicamente](htmx-polling.md): pedir el mismo fragmento cada pocos segundos.
|
||||
177
doc/v0.6/es/src/how-to/htmx-polling.md
Normal file
177
doc/v0.6/es/src/how-to/htmx-polling.md
Normal file
|
|
@ -0,0 +1,177 @@
|
|||
# Actualizar periódicamente
|
||||
|
||||
**Objetivo:** que una parte de la página se refresque sola cada pocos segundos (el progreso de una
|
||||
tarea larga, un contador, el estado de un servicio) y que deje de hacerlo cuando ya no haga falta.
|
||||
|
||||
Partimos de una aplicación con [HTMX añadido](htmx-setup.md).
|
||||
|
||||
## 1. Sondear cada pocos segundos
|
||||
|
||||
Con `hx-trigger="every 2s"`, el elemento repite su petición cada dos segundos mientras siga en la
|
||||
página:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Html {
|
||||
Html::with(|_| html! {
|
||||
div hx-get="/sensors" hx-trigger="every 2s" {
|
||||
p { "Reading the sensors..." }
|
||||
}
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
La ruta devuelve el contenido actualizado y HTMX lo pone dentro del `div`. Es la forma más
|
||||
sencilla de mantener un dato al día, sin conexiones permanentes ni JavaScript.
|
||||
|
||||
## 2. Parar cuando termina
|
||||
|
||||
Para el progreso de una tarea, el sondeo debe acabar cuando la tarea acaba. El truco es que **cada
|
||||
respuesta decide si sigue el sondeo**: el fragmento sustituye al elemento entero (`outerHTML`) y
|
||||
sólo lleva `hx-trigger` mientras la tarea no ha terminado.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
fn progress(percent: u64) -> Markup {
|
||||
if percent < 100 {
|
||||
html! {
|
||||
div id="watering" hx-get="/watering" hx-trigger="every 1s" hx-swap="outerHTML" {
|
||||
progress value=(percent) max="100" {}
|
||||
" " (percent) "%"
|
||||
}
|
||||
}
|
||||
} else {
|
||||
html! {
|
||||
div id="watering" {
|
||||
p { "Watering finished." }
|
||||
button hx-post="/watering" hx-target="#watering" hx-swap="outerHTML" {
|
||||
"Water again"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Cuando llega la versión final, sin `hx-trigger`, ya no queda nada que sondee.
|
||||
|
||||
Si prefieres no sustituir el elemento, hay otra forma de parar: responder con el código de estado
|
||||
**286**. HTMX lo interpreta como «deja de sondear».
|
||||
|
||||
## 3. Arrancar la tarea
|
||||
|
||||
Un botón inicia la tarea con un `POST`; la respuesta es el primer fragmento de progreso, que ya
|
||||
sondea por su cuenta:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use std::sync::Mutex;
|
||||
# use std::time::Instant;
|
||||
# static STARTED: Mutex<Option<Instant>> = Mutex::new(None);
|
||||
# fn progress(_: u64) -> Markup { html! {} }
|
||||
# fn started() -> std::sync::MutexGuard<'static, Option<Instant>> { STARTED.lock().unwrap() }
|
||||
async fn start() -> Markup {
|
||||
*started() = Some(Instant::now());
|
||||
progress(0)
|
||||
}
|
||||
```
|
||||
|
||||
En una aplicación real, `start` lanzaría el trabajo en segundo plano y guardaría su estado; la ruta
|
||||
del sondeo sólo lo consulta. Aquí, para no depender de nada, el progreso se calcula a partir del
|
||||
tiempo transcurrido.
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use std::sync::{Mutex, MutexGuard};
|
||||
use std::time::Instant;
|
||||
|
||||
// Seconds that the simulated watering lasts.
|
||||
const DURATION: u64 = 5;
|
||||
|
||||
static STARTED: Mutex<Option<Instant>> = Mutex::new(None);
|
||||
|
||||
fn started() -> MutexGuard<'static, Option<Instant>> {
|
||||
STARTED.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
|
||||
}
|
||||
|
||||
struct Watering;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Watering {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(home))
|
||||
.route("/watering", web::get(status).post(start))
|
||||
}
|
||||
}
|
||||
|
||||
fn progress(percent: u64) -> Markup {
|
||||
if percent < 100 {
|
||||
html! {
|
||||
div id="watering" hx-get="/watering" hx-trigger="every 1s" hx-swap="outerHTML" {
|
||||
progress value=(percent) max="100" {}
|
||||
" " (percent) "%"
|
||||
}
|
||||
}
|
||||
} else {
|
||||
html! {
|
||||
div id="watering" {
|
||||
p { "Watering finished." }
|
||||
button hx-post="/watering" hx-target="#watering" hx-swap="outerHTML" {
|
||||
"Water again"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Watering"))
|
||||
.with_child(Html::with(|_| html! {
|
||||
h1 { "Watering" }
|
||||
div id="watering" {
|
||||
button hx-post="/watering" hx-target="#watering" hx-swap="outerHTML" {
|
||||
"Start watering"
|
||||
}
|
||||
}
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn start() -> Markup {
|
||||
*started() = Some(Instant::now());
|
||||
progress(0)
|
||||
}
|
||||
|
||||
async fn status() -> Markup {
|
||||
let elapsed = started().map_or(DURATION, |since| since.elapsed().as_secs());
|
||||
progress((elapsed * 100 / DURATION).min(100))
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Watering).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Pulsa *Start watering*: aparece una barra que avanza cada segundo.
|
||||
2. A los cinco segundos, la barra da paso a «Watering finished.». En la pestaña *Red*, las
|
||||
peticiones a `/watering` se detienen.
|
||||
3. *Water again* vuelve a empezar.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Dirigir al navegador desde el servidor](htmx-responses.md): avisar a otras partes de la página
|
||||
cuando algo termina.
|
||||
- [Cargar contenido bajo demanda](htmx-load.md).
|
||||
224
doc/v0.6/es/src/how-to/htmx-responses.md
Normal file
224
doc/v0.6/es/src/how-to/htmx-responses.md
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
# Dirigir al navegador desde el servidor
|
||||
|
||||
**Objetivo:** que sea el servidor, y no los atributos de la página, quien decida qué pasa tras una
|
||||
petición: poner la respuesta en otro sitio, avisar a otras partes de la página, cambiar la URL o
|
||||
redirigir.
|
||||
|
||||
Partimos de una aplicación con [HTMX añadido](htmx-setup.md). Todo se hace con `HtmxResponse`, que
|
||||
añade a la respuesta las cabeceras `HX-*` que HTMX entiende.
|
||||
|
||||
## 1. Cambiar el destino según el resultado
|
||||
|
||||
Un formulario de suscripción coloca su respuesta en `#signup`. Si el correo no es válido, el error
|
||||
debe ir a otro sitio, junto al campo. La ruta lo decide:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct Signup {
|
||||
email: String,
|
||||
}
|
||||
|
||||
fn looks_like_an_email(email: &str) -> bool {
|
||||
email
|
||||
.split_once('@')
|
||||
.is_some_and(|(name, domain)| !name.is_empty() && domain.contains('.'))
|
||||
}
|
||||
|
||||
async fn subscribe(web::Form(signup): web::Form<Signup>) -> HtmxResponse {
|
||||
if !looks_like_an_email(&signup.email) {
|
||||
return HtmxResponse::new(html! { "That does not look like an email." })
|
||||
.retarget("#signup-error")
|
||||
.reswap(hx::swap::INNER_HTML);
|
||||
}
|
||||
// ... store the subscription ...
|
||||
HtmxResponse::new(html! { p { "Subscribed! See you at the next harvest." } })
|
||||
}
|
||||
```
|
||||
|
||||
`retarget()` y `reswap()` mandan sobre `hx-target` y `hx-swap`. El formulario sigue en su sitio y
|
||||
el usuario puede corregir el correo.
|
||||
|
||||
## 2. Avisar a otras partes de la página
|
||||
|
||||
Tras una suscripción, el contador de suscriptores de la cabecera debería actualizarse. En lugar de
|
||||
que la ruta sepa qué hay en la cabecera, **dispara un evento**:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_htmx::prelude::*;
|
||||
# fn f() -> HtmxResponse {
|
||||
HtmxResponse::new(html! { p { "Subscribed! See you at the next harvest." } })
|
||||
.trigger("subscribed")
|
||||
# }
|
||||
```
|
||||
|
||||
Y quien quiera enterarse, lo escucha. El evento sube hasta `body`, así que basta con
|
||||
`from:body`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Html {
|
||||
Html::with(|_| html! {
|
||||
span hx-get="/subscribers" hx-trigger="subscribed from:body" { "0" }
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
Las dos partes no se conocen: el formulario anuncia y el contador escucha. Puedes añadir más
|
||||
oyentes sin tocar la ruta. Para enviar varios eventos o datos con ellos, `trigger()` admite una
|
||||
lista separada por comas o un objeto JSON.
|
||||
|
||||
## 3. Redirigir
|
||||
|
||||
Tras una acción con HTMX, una redirección normal (`303`) la seguiría HTMX por su cuenta y pondría
|
||||
la página nueva **dentro** del destino. Para cambiar de página de verdad, usa `redirect()`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
async fn close_season() -> HtmxResponse {
|
||||
// ... close the season ...
|
||||
HtmxResponse::empty().redirect("/season/closed")
|
||||
}
|
||||
```
|
||||
|
||||
`location()` es la alternativa suave: navega con HTMX, sin recargar los estilos y *scripts* de la
|
||||
página.
|
||||
|
||||
Con las dos, los avisos que añadas con `with_message()` esperan a la página de destino, como tras
|
||||
una redirección normal: convierte antes la respuesta con `.into_response()`.
|
||||
|
||||
## Las cabeceras disponibles
|
||||
|
||||
| Método | Cabecera | Efecto |
|
||||
|---|---|---|
|
||||
| `retarget(selector)` | `HX-Retarget` | Pone la respuesta en otro elemento |
|
||||
| `reswap(estrategia)` | `HX-Reswap` | Cambia cómo se coloca (`innerHTML`, `outerHTML`...) |
|
||||
| `reselect(selector)` | `HX-Reselect` | Usa sólo una parte de la respuesta |
|
||||
| `trigger(eventos)` | `HX-Trigger` | Dispara eventos al recibir la respuesta |
|
||||
| `trigger_after_swap(eventos)` | `HX-Trigger-After-Swap` | ...después de colocarla |
|
||||
| `trigger_after_settle(eventos)` | `HX-Trigger-After-Settle` | ...cuando se ha asentado |
|
||||
| `push_url(url)` | `HX-Push-Url` | Añade una entrada al historial |
|
||||
| `replace_url(url)` | `HX-Replace-Url` | Cambia la URL sin añadir entrada |
|
||||
| `redirect(url)` | `HX-Redirect` | Navegación completa a otra página |
|
||||
| `location(url)` | `HX-Location` | Navegación con HTMX, sin recargar la página |
|
||||
| `refresh()` | `HX-Refresh` | Recarga la página entera |
|
||||
| `oob(markup)` | - | Añade un fragmento [fuera de banda](htmx-delete.md#2-la-ruta-devuelve-un-fragmento-vacío) |
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
use std::sync::atomic::{AtomicUsize, Ordering};
|
||||
|
||||
static SUBSCRIBERS: AtomicUsize = AtomicUsize::new(0);
|
||||
|
||||
struct Newsletter;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Newsletter {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(home))
|
||||
.route("/subscribe", web::post(subscribe))
|
||||
.route("/subscribers", web::get(subscribers))
|
||||
.route("/season/close", web::post(close_season))
|
||||
.route("/season/closed", web::get(season_closed))
|
||||
}
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Newsletter"))
|
||||
.with_child(Html::with(|_| html! {
|
||||
p {
|
||||
"Subscribers: "
|
||||
span hx-get="/subscribers" hx-trigger="subscribed from:body" {
|
||||
(SUBSCRIBERS.load(Ordering::Relaxed))
|
||||
}
|
||||
}
|
||||
div id="signup" {
|
||||
form hx-post="/subscribe" hx-target="#signup" {
|
||||
input type="email" name="email" placeholder="you@example.com";
|
||||
button type="submit" { "Subscribe" }
|
||||
p id="signup-error" {}
|
||||
}
|
||||
}
|
||||
button hx-post="/season/close" hx-confirm="Close the season?" { "Close the season" }
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct Signup {
|
||||
email: String,
|
||||
}
|
||||
|
||||
fn looks_like_an_email(email: &str) -> bool {
|
||||
email
|
||||
.split_once('@')
|
||||
.is_some_and(|(name, domain)| !name.is_empty() && domain.contains('.'))
|
||||
}
|
||||
|
||||
async fn subscribe(web::Form(signup): web::Form<Signup>) -> HtmxResponse {
|
||||
if !looks_like_an_email(&signup.email) {
|
||||
return HtmxResponse::new(html! { "That does not look like an email." })
|
||||
.retarget("#signup-error")
|
||||
.reswap(hx::swap::INNER_HTML);
|
||||
}
|
||||
SUBSCRIBERS.fetch_add(1, Ordering::Relaxed);
|
||||
HtmxResponse::new(html! { p { "Subscribed! See you at the next harvest." } })
|
||||
.trigger("subscribed")
|
||||
}
|
||||
|
||||
async fn subscribers() -> Markup {
|
||||
html! { (SUBSCRIBERS.load(Ordering::Relaxed)) }
|
||||
}
|
||||
|
||||
async fn close_season() -> HtmxResponse {
|
||||
HtmxResponse::empty().redirect("/season/closed")
|
||||
}
|
||||
|
||||
async fn season_closed(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Season closed"))
|
||||
.with_child(Html::with(|_| html! { h1 { "The season is closed. See you in spring!" } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Newsletter).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
El formulario de este ejemplo está escrito en `html!` para que se vea entero; con `Form` y sus
|
||||
campos, los atributos se ponen igual, con `with_prop()`.
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Escribe `ana@garden` y suscríbete: el navegador lo da por bueno, pero el servidor exige un
|
||||
dominio con punto. El aviso aparece bajo el campo y el formulario sigue ahí.
|
||||
2. Escribe un correo válido: el formulario se sustituye por la confirmación y el contador de
|
||||
suscriptores sube, sin que la ruta lo haya tocado.
|
||||
3. Pulsa *Close the season* y acepta: el navegador cambia de página.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [HTMX: atributos, cabeceras y respuestas](../reference/htmx.md), la referencia completa.
|
||||
- [Probar rutas y componentes](testing.md): las cabeceras `HX-*` también se pueden comprobar en
|
||||
las pruebas.
|
||||
219
doc/v0.6/es/src/how-to/htmx-search.md
Normal file
219
doc/v0.6/es/src/how-to/htmx-search.md
Normal file
|
|
@ -0,0 +1,219 @@
|
|||
# Buscar mientras se escribe
|
||||
|
||||
**Objetivo:** un buscador que filtra los resultados a medida que el usuario escribe, que deja en la
|
||||
barra de direcciones una URL que se puede compartir y que funciona también sin JavaScript.
|
||||
|
||||
Partimos de una aplicación con [HTMX añadido](htmx-setup.md).
|
||||
|
||||
## 1. Un buscador de toda la vida
|
||||
|
||||
Empieza por lo que funcionaría sin HTMX: un formulario `GET` que envía `q` a `/plants`, y una ruta
|
||||
que muestra los resultados.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
const PLANTS: &[&str] = &[
|
||||
"Basil", "Bean", "Beetroot", "Cabbage", "Carrot", "Chard", "Courgette", "Cucumber", "Garlic",
|
||||
"Leek", "Lettuce", "Onion", "Parsley", "Pepper", "Potato", "Pumpkin", "Radish", "Spinach",
|
||||
"Strawberry", "Tomato",
|
||||
];
|
||||
|
||||
fn results(q: &str) -> Markup {
|
||||
let q = q.trim().to_lowercase();
|
||||
let found: Vec<&str> = PLANTS
|
||||
.iter()
|
||||
.copied()
|
||||
.filter(|plant| plant.to_lowercase().contains(&q))
|
||||
.collect();
|
||||
html! {
|
||||
div id="results" {
|
||||
@if found.is_empty() {
|
||||
p { "No plants found." }
|
||||
} @else {
|
||||
ul {
|
||||
@for plant in &found {
|
||||
li { (plant) }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
El contenedor `#results` forma parte del fragmento. Así, al sustituirlo entero (`outerHTML`), el
|
||||
destino sigue existiendo para la búsqueda siguiente.
|
||||
|
||||
## 2. Que busque al escribir
|
||||
|
||||
Al formulario se le añaden cinco atributos:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
fn search_form(q: &str) -> Form {
|
||||
Form::new()
|
||||
.with_action("/plants")
|
||||
.with_method(form::Method::Get)
|
||||
.with_prop(PropsOp::set(hx::GET, "/plants"))
|
||||
.with_prop(PropsOp::set(hx::TRIGGER, "input delay:300ms, submit"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#results"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::OUTER_HTML))
|
||||
.with_prop(PropsOp::set(hx::REPLACE_URL, "true"))
|
||||
.with_child(
|
||||
form::input::Field::search()
|
||||
.with_name("q")
|
||||
.with_value(q)
|
||||
.with_label(Lc::n("Search plants")),
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
- `hx-trigger="input delay:300ms, submit"`: busca cuando cambia el texto, pero espera a que el
|
||||
usuario lleve 300 ms sin teclear. Así, escribir «tomato» hace una petición, no seis. `submit`
|
||||
mantiene la tecla Intro.
|
||||
- El evento `input` sube desde el campo hasta el formulario, y una petición `GET` de un formulario
|
||||
incluye todos sus campos: no hay que decir qué enviar.
|
||||
- `hx-replace-url="true"`: la barra de direcciones pasa a `/plants?q=tom`, sin llenar el historial
|
||||
con una entrada por búsqueda.
|
||||
|
||||
## 3. Una ruta, dos respuestas
|
||||
|
||||
La URL que queda en la barra se puede recargar o compartir. Esa petición llega **sin** HTMX y
|
||||
espera una página entera; las de HTMX, sólo los resultados:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_htmx::prelude::*;
|
||||
# fn results(_: &str) -> Markup { html! {} }
|
||||
# fn search_form(_: &str) -> Form { Form::new() }
|
||||
use serde::Deserialize;
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct Search {
|
||||
#[serde(default)]
|
||||
q: String,
|
||||
}
|
||||
|
||||
async fn plants(request: HttpRequest, web::Query(search): web::Query<Search>) -> Response {
|
||||
if request.is_htmx() {
|
||||
return HtmxResponse::new(results(&search.q)).into_response();
|
||||
}
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Plants"))
|
||||
.with_child(search_form(&search.q))
|
||||
.with_child(Html::with(move |_| results(&search.q)))
|
||||
.render()
|
||||
.await
|
||||
.into_response()
|
||||
}
|
||||
```
|
||||
|
||||
Sin JavaScript, el formulario se envía como siempre y la misma ruta devuelve la página completa: el
|
||||
buscador funciona igual, sólo que pulsando Intro.
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
const PLANTS: &[&str] = &[
|
||||
"Basil", "Bean", "Beetroot", "Cabbage", "Carrot", "Chard", "Courgette", "Cucumber", "Garlic",
|
||||
"Leek", "Lettuce", "Onion", "Parsley", "Pepper", "Potato", "Pumpkin", "Radish", "Spinach",
|
||||
"Strawberry", "Tomato",
|
||||
];
|
||||
|
||||
struct PlantFinder;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for PlantFinder {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(|| async { Redirect::see_other("/plants") }))
|
||||
.route("/plants", web::get(plants))
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct Search {
|
||||
#[serde(default)]
|
||||
q: String,
|
||||
}
|
||||
|
||||
async fn plants(request: HttpRequest, web::Query(search): web::Query<Search>) -> Response {
|
||||
if request.is_htmx() {
|
||||
return HtmxResponse::new(results(&search.q)).into_response();
|
||||
}
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Plants"))
|
||||
.with_child(search_form(&search.q))
|
||||
.with_child(Html::with(move |_| results(&search.q)))
|
||||
.render()
|
||||
.await
|
||||
.into_response()
|
||||
}
|
||||
|
||||
fn search_form(q: &str) -> Form {
|
||||
Form::new()
|
||||
.with_action("/plants")
|
||||
.with_method(form::Method::Get)
|
||||
.with_prop(PropsOp::set(hx::GET, "/plants"))
|
||||
.with_prop(PropsOp::set(hx::TRIGGER, "input delay:300ms, submit"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#results"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::OUTER_HTML))
|
||||
.with_prop(PropsOp::set(hx::REPLACE_URL, "true"))
|
||||
.with_child(
|
||||
form::input::Field::search()
|
||||
.with_name("q")
|
||||
.with_value(q)
|
||||
.with_label(Lc::n("Search plants")),
|
||||
)
|
||||
}
|
||||
|
||||
fn results(q: &str) -> Markup {
|
||||
let q = q.trim().to_lowercase();
|
||||
let found: Vec<&str> = PLANTS
|
||||
.iter()
|
||||
.copied()
|
||||
.filter(|plant| plant.to_lowercase().contains(&q))
|
||||
.collect();
|
||||
html! {
|
||||
div id="results" {
|
||||
@if found.is_empty() {
|
||||
p { "No plants found." }
|
||||
} @else {
|
||||
ul {
|
||||
@for plant in &found {
|
||||
li { (plant) }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&PlantFinder).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Abre <http://localhost:8080/plants> y escribe `to`: la lista se reduce a *Potato* y *Tomato*
|
||||
sin pulsar nada, y la barra de direcciones muestra `/plants?q=to`.
|
||||
2. Recarga la página: sale la misma búsqueda, ya resuelta por el servidor.
|
||||
3. En la pestaña *Red*, escribir una palabra seguida produce una sola petición.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Ordenar y paginar sin recargar](htmx-tables.md): el mismo patrón sobre una tabla con su
|
||||
paginador.
|
||||
- [Validar un campo al vuelo](htmx-validation.md).
|
||||
216
doc/v0.6/es/src/how-to/htmx-setup.md
Normal file
216
doc/v0.6/es/src/how-to/htmx-setup.md
Normal file
|
|
@ -0,0 +1,216 @@
|
|||
# Añadir HTMX a una aplicación
|
||||
|
||||
**Objetivo:** que tus páginas carguen [HTMX](https://htmx.org), que sus elementos pidan fragmentos
|
||||
de HTML al servidor y que tus rutas sepan responderlos.
|
||||
|
||||
Si es tu primer contacto con HTMX, el tutorial [Tareas del huerto con
|
||||
HTMX](../tutorials/htmx-tasks.md) lo presenta paso a paso. Esta guía reúne lo esencial para
|
||||
cualquier aplicación.
|
||||
|
||||
## 1. Declara la extensión
|
||||
|
||||
Añade `pagetop-htmx` a `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
pagetop-htmx = { git = "https://git.cillero.es/manuelcillero/pagetop" }
|
||||
```
|
||||
|
||||
Y declárala como dependencia de tu extensión:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
pub struct MyApp;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for MyApp {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
No hace falta nada más: la extensión añade el *script* de HTMX 2 a **todas** las páginas, con
|
||||
`defer`, y lo sirve desde el propio binario. No hay que descargar nada ni configurar una CDN.
|
||||
|
||||
## 2. Escribe atributos `hx-*` en `html!`
|
||||
|
||||
Los atributos de HTMX se escriben en `html!` como cualquier otro:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Html {
|
||||
Html::with(|_| html! {
|
||||
button hx-get="/time" hx-target="#time" { "What time is it?" }
|
||||
span id="time" {}
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
Al pulsar el botón, HTMX hace `GET /time` y pone la respuesta dentro de `#time`. Los atributos
|
||||
principales:
|
||||
|
||||
| Atributo | Qué indica | Por defecto |
|
||||
|---|---|---|
|
||||
| `hx-get`, `hx-post`, `hx-put`, `hx-patch`, `hx-delete` | Método y URL de la petición | - |
|
||||
| `hx-trigger` | Qué evento la lanza | `click`; `change` en campos; `submit` en formularios |
|
||||
| `hx-target` | Dónde va la respuesta (selector CSS, `this`, `closest tr`...) | El propio elemento |
|
||||
| `hx-swap` | Cómo se coloca | `innerHTML`: sustituye el contenido |
|
||||
|
||||
La lista completa está en la [referencia de HTMX](../reference/htmx.md).
|
||||
|
||||
## 3. Ponlos en componentes con `with_prop()`
|
||||
|
||||
Los componentes no conocen HTMX, pero todos aceptan atributos con `with_prop()`. El módulo `hx` de
|
||||
`pagetop-htmx` tiene una constante para cada atributo y para sus valores habituales:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
# fn f() -> Button {
|
||||
Button::plain(Lc::n("What time is it?"))
|
||||
.with_prop(PropsOp::set(hx::GET, "/time"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#time"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::INNER_HTML))
|
||||
# }
|
||||
```
|
||||
|
||||
Con las constantes, una errata como `hx::GTE` no compila; escrita como texto, `"hx-gte"` fallaría
|
||||
en silencio en el navegador.
|
||||
|
||||
## 4. Responde con un fragmento
|
||||
|
||||
Una ruta para HTMX devuelve **sólo el trozo de HTML** que va en el destino, no una página. Lo más
|
||||
sencillo es devolver `Markup`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
async fn time() -> Markup {
|
||||
html! { (Utc::now().format("%H:%M:%S")) " UTC" }
|
||||
}
|
||||
```
|
||||
|
||||
Si además necesitas cabeceras de HTMX (cambiar el destino, disparar eventos, redirigir...),
|
||||
devuelve un `HtmxResponse`. Lo verás en [Dirigir al navegador desde el
|
||||
servidor](htmx-responses.md):
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
async fn time() -> HtmxResponse {
|
||||
HtmxResponse::new(html! { (Utc::now().format("%H:%M:%S")) " UTC" })
|
||||
.trigger("timeShown")
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Renderiza componentes en un fragmento
|
||||
|
||||
Fuera de una `Page`, un componente se renderiza con un `Context` creado a partir de la petición. El
|
||||
contexto aporta el idioma, el tema y las rutas, así que el fragmento sale igual que dentro de la
|
||||
página:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
async fn notice(request: HttpRequest) -> HtmxResponse {
|
||||
let mut cx = Context::new(request);
|
||||
let mut badge = Badge::success(Lc::n("Saved"));
|
||||
HtmxResponse::new(badge.render(&mut cx).await)
|
||||
}
|
||||
```
|
||||
|
||||
> **Los recursos de un componente no viajan en un fragmento.** Si un componente añade su hoja de
|
||||
> estilos o su *script* al contexto, en una página acaban en el `<head>`; en un fragmento suelto no
|
||||
> hay `<head>` donde ponerlos. Asegúrate de que la página que recibe el fragmento ya los carga, por
|
||||
> ejemplo usando ese mismo componente en ella o añadiéndolos con `with_assets()`.
|
||||
|
||||
## 6. Una ruta, dos respuestas
|
||||
|
||||
Cuando la misma URL puede pedirse con HTMX (para un fragmento) o directamente (al recargar, desde
|
||||
un enlace compartido o sin JavaScript), comprueba quién llama con `is_htmx()`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
async fn plants(request: HttpRequest) -> Response {
|
||||
let list = html! { ul { li { "Tomato" } li { "Pepper" } } };
|
||||
if request.is_htmx() {
|
||||
HtmxResponse::new(list).into_response()
|
||||
} else {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Plants"))
|
||||
.with_child(Html::with(move |_| list.clone()))
|
||||
.render()
|
||||
.await
|
||||
.into_response()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`is_htmx()` lee la cabecera `HX-Request` que HTMX añade a sus peticiones. El trait
|
||||
`HtmxRequestExt` también ofrece `hx_target()`, `hx_trigger_id()`, `is_boosted()`... para leer las
|
||||
demás.
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
struct Clock;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Clock {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(home))
|
||||
.route("/time", web::get(time))
|
||||
}
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Clock"))
|
||||
.with_child(
|
||||
Button::plain(Lc::n("What time is it?"))
|
||||
.with_prop(PropsOp::set(hx::GET, "/time"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#time")),
|
||||
)
|
||||
.with_child(Html::with(|_| html! { p id="time" { "Not asked yet." } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn time(request: HttpRequest) -> HtmxResponse {
|
||||
let mut cx = Context::new(request);
|
||||
let mut badge = Badge::info(Lc::n(Utc::now().format("%H:%M:%S UTC").to_string()));
|
||||
HtmxResponse::new(badge.render(&mut cx).await)
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Clock).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Arranca la aplicación y abre <http://localhost:8080>.
|
||||
2. Pulsa el botón: la hora aparece en una etiqueta, sin recargar.
|
||||
3. En las herramientas de desarrollo del navegador (pestaña *Red*), la petición a `/time` lleva la
|
||||
cabecera `HX-Request: true` y la respuesta es una sola etiqueta `<span>`.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Cargar contenido bajo demanda](htmx-load.md): al pulsar, al cargar la página o al hacerse
|
||||
visible.
|
||||
- [Probar rutas y componentes](testing.md): cómo probar una ruta de HTMX sin navegador.
|
||||
- [HTML por la red: por qué HTMX](../explanation/htmx.md).
|
||||
252
doc/v0.6/es/src/how-to/htmx-tables.md
Normal file
252
doc/v0.6/es/src/how-to/htmx-tables.md
Normal file
|
|
@ -0,0 +1,252 @@
|
|||
# Ordenar y paginar sin recargar
|
||||
|
||||
**Objetivo:** una tabla que se ordena al pulsar sus cabeceras y se pagina con su `Pager`, sustituyendo
|
||||
sólo la tabla, con URLs reales en la barra de direcciones y sin perder nada si JavaScript no está
|
||||
disponible.
|
||||
|
||||
Partimos de una aplicación con [HTMX añadido](htmx-setup.md) y de lo visto en [Mostrar tablas
|
||||
ordenables y paginadas](tables.md): `Table`, `SortLink` y `Pager` ya generan enlaces normales que
|
||||
funcionan sin HTMX. Aquí sólo se les añade el comportamiento.
|
||||
|
||||
## 1. Un contenedor como destino
|
||||
|
||||
La tabla y su paginador van juntos en un `Container` con `id`. Ése es el destino de todas las
|
||||
peticiones: al ordenar o cambiar de página, se sustituyen los dos.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn table() -> Table { Table::new() }
|
||||
# fn pager() -> Pager { Pager::new() }
|
||||
# fn f() -> Container {
|
||||
Container::new()
|
||||
.with_id("harvests")
|
||||
.with_child(table())
|
||||
.with_child(pager())
|
||||
# }
|
||||
```
|
||||
|
||||
## 2. Cabeceras que ordenan con HTMX
|
||||
|
||||
`hx_table::sort_link()` crea el enlace de una cabecera con los atributos de HTMX ya puestos: hace
|
||||
`GET` a la misma URL del enlace, sustituye el destino, vuelve arriba y actualiza la barra de
|
||||
direcciones. Sólo hay que darle la URL, el destino y la dirección actual de esa columna:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
fn sortable(cx: &Context, field: &str, label: Lc, sort: &str, dir: SortDir) -> table::Column {
|
||||
// `Some` only if the table is sorted by this column right now.
|
||||
let active = (field == sort).then_some(dir);
|
||||
let href = cx
|
||||
.route("/harvests")
|
||||
.with_param("sort", field)
|
||||
.with_param("dir", SortDir::next_for(active));
|
||||
table::Column::new(label).with_sort(hx_table::sort_link(href, "#harvests", active))
|
||||
}
|
||||
```
|
||||
|
||||
`SortDir::next_for()` calcula la dirección del siguiente clic: ascendente si la columna no ordena
|
||||
ahora, la contraria si ya lo hace. `cx.route()` conserva el parámetro `?lang=` cuando lo hay.
|
||||
|
||||
## 3. Un paginador que navega con HTMX
|
||||
|
||||
`Pager` no necesita atributos en cada enlace: con `hx-boost` en su `<nav>`, HTMX convierte en
|
||||
peticiones AJAX todos los enlaces que contiene, reutilizando su `href`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
|
||||
# fn f(sort: &str, dir: SortDir, page: u64, total: u64) -> Pager {
|
||||
Pager::new()
|
||||
.with_base_path("/harvests")
|
||||
.with_extra_query("sort", sort)
|
||||
.with_extra_query("dir", dir.as_str())
|
||||
.with_current_page(page)
|
||||
.with_items_per_page(5)
|
||||
.with_total_items(total)
|
||||
.with_prop(PropsOp::set(hx::BOOST, "true"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#harvests"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::OUTER_HTML_SCROLL_TOP))
|
||||
.with_prop(PropsOp::set(hx::PUSH_URL, "true"))
|
||||
# }
|
||||
```
|
||||
|
||||
`with_extra_query()` mantiene el orden al cambiar de página.
|
||||
|
||||
## 4. La ruta: página entera o sólo la tabla
|
||||
|
||||
Una sola ruta atiende todo. Lee el estado de la URL, construye el contenedor y lo devuelve solo (con
|
||||
HTMX) o dentro de una página (sin HTMX, al recargar o desde un enlace compartido). En los dos casos
|
||||
usa un `Context`: el de la página, o uno creado a partir de la petición.
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_htmx::prelude::*;
|
||||
# fn harvests(_: &Context, _: &str, _: SortDir, _: u64) -> Container { Container::new() }
|
||||
use serde::Deserialize;
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct ListQuery {
|
||||
sort: Option<String>,
|
||||
dir: Option<String>,
|
||||
page: Option<u64>,
|
||||
}
|
||||
|
||||
async fn list(request: HttpRequest, web::Query(query): web::Query<ListQuery>) -> Response {
|
||||
let sort = query.sort.as_deref().unwrap_or("crop");
|
||||
let dir = SortDir::from_query(query.dir.as_deref());
|
||||
let page = query.page.unwrap_or(1).max(1);
|
||||
|
||||
if request.is_htmx() {
|
||||
let mut cx = Context::new(request);
|
||||
let mut table = harvests(&cx, sort, dir, page);
|
||||
return HtmxResponse::new(table.render(&mut cx).await).into_response();
|
||||
}
|
||||
let mut full = Page::new(request).with_title(Lc::n("Harvests"));
|
||||
let table = harvests(full.context(), sort, dir, page);
|
||||
full.with_child(table).render().await.into_response()
|
||||
}
|
||||
```
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
const PER_PAGE: u64 = 5;
|
||||
|
||||
struct Harvest {
|
||||
crop: &'static str,
|
||||
plot: &'static str,
|
||||
kilos: u32,
|
||||
}
|
||||
|
||||
const HARVESTS: &[Harvest] = &[
|
||||
Harvest { crop: "Tomato", plot: "A1", kilos: 42 },
|
||||
Harvest { crop: "Lettuce", plot: "A2", kilos: 12 },
|
||||
Harvest { crop: "Pepper", plot: "B1", kilos: 18 },
|
||||
Harvest { crop: "Courgette", plot: "B2", kilos: 35 },
|
||||
Harvest { crop: "Onion", plot: "A1", kilos: 20 },
|
||||
Harvest { crop: "Potato", plot: "C1", kilos: 60 },
|
||||
Harvest { crop: "Bean", plot: "C2", kilos: 9 },
|
||||
Harvest { crop: "Pumpkin", plot: "B1", kilos: 51 },
|
||||
Harvest { crop: "Chard", plot: "A2", kilos: 14 },
|
||||
Harvest { crop: "Carrot", plot: "C1", kilos: 16 },
|
||||
Harvest { crop: "Garlic", plot: "C2", kilos: 7 },
|
||||
Harvest { crop: "Strawberry", plot: "B2", kilos: 11 },
|
||||
];
|
||||
|
||||
struct HarvestLog;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for HarvestLog {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(|| async { Redirect::see_other("/harvests") }))
|
||||
.route("/harvests", web::get(list))
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct ListQuery {
|
||||
sort: Option<String>,
|
||||
dir: Option<String>,
|
||||
page: Option<u64>,
|
||||
}
|
||||
|
||||
async fn list(request: HttpRequest, web::Query(query): web::Query<ListQuery>) -> Response {
|
||||
let sort = query.sort.as_deref().unwrap_or("crop");
|
||||
let dir = SortDir::from_query(query.dir.as_deref());
|
||||
let page = query.page.unwrap_or(1).max(1);
|
||||
|
||||
if request.is_htmx() {
|
||||
let mut cx = Context::new(request);
|
||||
let mut table = harvests(&cx, sort, dir, page);
|
||||
return HtmxResponse::new(table.render(&mut cx).await).into_response();
|
||||
}
|
||||
let mut full = Page::new(request).with_title(Lc::n("Harvests"));
|
||||
let table = harvests(full.context(), sort, dir, page);
|
||||
full.with_child(table).render().await.into_response()
|
||||
}
|
||||
|
||||
fn harvests(cx: &Context, sort: &str, dir: SortDir, page: u64) -> Container {
|
||||
let mut rows: Vec<&Harvest> = HARVESTS.iter().collect();
|
||||
match sort {
|
||||
"kilos" => rows.sort_by_key(|harvest| harvest.kilos),
|
||||
_ => rows.sort_by_key(|harvest| harvest.crop),
|
||||
}
|
||||
if dir == SortDir::Desc {
|
||||
rows.reverse();
|
||||
}
|
||||
|
||||
let mut table = Table::new()
|
||||
.with_column(sortable(cx, "crop", Lc::n("Crop"), sort, dir))
|
||||
.with_column(table::Column::new(Lc::n("Plot")))
|
||||
.with_column(sortable(cx, "kilos", Lc::n("Kilos"), sort, dir));
|
||||
let skip = ((page - 1) * PER_PAGE) as usize;
|
||||
for harvest in rows.iter().skip(skip).take(PER_PAGE as usize) {
|
||||
table = table.with_row(
|
||||
table::Row::new()
|
||||
.with_cell(harvest.crop)
|
||||
.with_cell(harvest.plot)
|
||||
.with_cell(harvest.kilos.to_string()),
|
||||
);
|
||||
}
|
||||
|
||||
let pager = Pager::new()
|
||||
.with_base_path("/harvests")
|
||||
.with_extra_query("sort", sort)
|
||||
.with_extra_query("dir", dir.as_str())
|
||||
.with_current_page(page)
|
||||
.with_items_per_page(PER_PAGE)
|
||||
.with_total_items(rows.len() as u64)
|
||||
.with_prop(PropsOp::set(hx::BOOST, "true"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#harvests"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::OUTER_HTML_SCROLL_TOP))
|
||||
.with_prop(PropsOp::set(hx::PUSH_URL, "true"));
|
||||
|
||||
Container::new()
|
||||
.with_id("harvests")
|
||||
.with_child(table)
|
||||
.with_child(pager)
|
||||
}
|
||||
|
||||
fn sortable(cx: &Context, field: &str, label: Lc, sort: &str, dir: SortDir) -> table::Column {
|
||||
// `Some` only if the table is sorted by this column right now.
|
||||
let active = (field == sort).then_some(dir);
|
||||
let href = cx
|
||||
.route("/harvests")
|
||||
.with_param("sort", field)
|
||||
.with_param("dir", SortDir::next_for(active));
|
||||
table::Column::new(label).with_sort(hx_table::sort_link(href, "#harvests", active))
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&HarvestLog).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Abre <http://localhost:8080/harvests>: cinco cosechas ordenadas por cultivo y un paginador de
|
||||
tres páginas.
|
||||
2. Pulsa la cabecera *Kilos*: la tabla se ordena de menos a más; púlsala otra vez, de más a menos.
|
||||
La barra de direcciones refleja cada estado (`?sort=kilos&dir=desc`).
|
||||
3. Ve a la página 2: se conserva el orden. Usa el botón *Atrás* del navegador y recarga: la URL
|
||||
muestra exactamente lo que había.
|
||||
4. Desactiva JavaScript y repite: todo funciona igual, con recargas de página completas.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Buscar mientras se escribe](htmx-search.md): añade un buscador que filtre la misma tabla.
|
||||
- [Cargar más al hacer *scroll*](htmx-infinite.md): la alternativa al paginador para listas que se
|
||||
leen de arriba abajo.
|
||||
315
doc/v0.6/es/src/how-to/htmx-validation.md
Normal file
315
doc/v0.6/es/src/how-to/htmx-validation.md
Normal file
|
|
@ -0,0 +1,315 @@
|
|||
# Validar un campo al vuelo
|
||||
|
||||
**Objetivo:** avisar de un error mientras el usuario rellena el formulario (un nombre de usuario ya
|
||||
ocupado, por ejemplo) y, al enviarlo, mostrar los errores **dentro** del formulario sin recargar la
|
||||
página ni perder lo escrito.
|
||||
|
||||
Partimos de una aplicación con [HTMX añadido](htmx-setup.md) y de lo visto en [Crear y procesar
|
||||
formularios](forms.md).
|
||||
|
||||
## 1. El formulario y su validación
|
||||
|
||||
Un formulario para unirse al huerto, con su validación en el servidor. Una función construye el
|
||||
formulario con los valores recibidos, para poder repetirlo sin perder lo escrito:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
const TAKEN: &[&str] = &["admin", "ana", "luke"];
|
||||
|
||||
#[derive(Default, Deserialize)]
|
||||
#[serde(default)]
|
||||
struct JoinData {
|
||||
username: String,
|
||||
email: String,
|
||||
}
|
||||
|
||||
fn validate(data: &JoinData) -> Option<Lc> {
|
||||
let username = data.username.trim();
|
||||
if username.chars().count() < 3 {
|
||||
Some(Lc::n("The username needs at least 3 characters."))
|
||||
} else if TAKEN.contains(&username) {
|
||||
Some(Lc::n("That username is already taken."))
|
||||
} else if !data.email.contains('@') {
|
||||
Some(Lc::n("Write a valid email."))
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`#[serde(default)]` permite deserializar el formulario aunque falte algún campo, lo que vendrá bien
|
||||
en el paso 2.
|
||||
|
||||
## 2. Comprobar un campo mientras se escribe
|
||||
|
||||
Los atributos `hx-*` de un campo se ponen con su `with_prop()`. El campo hace un `POST` a
|
||||
`/join/check` cuando el usuario deja de escribir medio segundo, y la respuesta va a `#username-check`,
|
||||
justo debajo:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
# #[derive(Default)]
|
||||
# struct JoinData { username: String, email: String }
|
||||
|
||||
fn username_field(data: &JoinData) -> form::input::Field {
|
||||
form::input::Field::text()
|
||||
.with_name("username")
|
||||
.with_value(&data.username)
|
||||
.with_label(Lc::n("Username"))
|
||||
.with_required(true)
|
||||
.with_prop(PropsOp::set(hx::POST, "/join/check"))
|
||||
.with_prop(PropsOp::set(hx::TRIGGER, "input delay:500ms"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#username-check"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::INNER_HTML))
|
||||
}
|
||||
```
|
||||
|
||||
`hx-swap` parece innecesario, porque `innerHTML` es el valor por defecto. Pero los atributos de
|
||||
HTMX **se heredan**: en el paso 3 el formulario tendrá `hx-swap="outerHTML"`, y el campo lo
|
||||
heredaría, así que la etiqueta sustituiría al propio `#username-check` y la siguiente comprobación
|
||||
ya no tendría dónde ir.
|
||||
|
||||
Una petición que no es `GET` incluye **todos** los campos del formulario que la contiene, así que la
|
||||
ruta recibe el mismo `JoinData`. Sólo mira el nombre:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_htmx::prelude::*;
|
||||
# const TAKEN: &[&str] = &[];
|
||||
# #[derive(Default, serde::Deserialize)]
|
||||
# #[serde(default)]
|
||||
# struct JoinData { username: String }
|
||||
async fn check_username(request: HttpRequest, web::Form(data): web::Form<JoinData>) -> HtmxResponse {
|
||||
let username = data.username.trim();
|
||||
if username.is_empty() {
|
||||
return HtmxResponse::empty();
|
||||
}
|
||||
let mut badge = if TAKEN.contains(&username) {
|
||||
Badge::severe(Lc::n("Already taken"))
|
||||
} else {
|
||||
Badge::success(Lc::n("Available"))
|
||||
};
|
||||
HtmxResponse::new(badge.render(&mut Context::new(request)).await)
|
||||
}
|
||||
```
|
||||
|
||||
> **Responde con 200, también a los errores.** Por defecto, HTMX **no coloca** las respuestas con
|
||||
> código 4xx o 5xx. Un error de validación es una respuesta normal que el usuario debe ver.
|
||||
|
||||
## 3. Errores dentro del formulario al enviarlo
|
||||
|
||||
Para que el formulario completo se envíe con HTMX y se sustituya por la respuesta, el formulario y
|
||||
sus mensajes van en un contenedor con `id`, y ése es el destino:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_htmx::prelude::*;
|
||||
# #[derive(Default)]
|
||||
# struct JoinData { username: String, email: String }
|
||||
# fn username_field(_: &JoinData) -> form::input::Field { form::input::Field::text() }
|
||||
fn join_box(data: &JoinData) -> Container {
|
||||
Container::new().with_id("join").with_child(Messages::new()).with_child(
|
||||
Form::new()
|
||||
.with_action("/join")
|
||||
.with_prop(PropsOp::set(hx::POST, "/join"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#join"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::OUTER_HTML))
|
||||
.with_child(username_field(data))
|
||||
.with_child(Html::with(|_| html! { div id="username-check" {} }))
|
||||
.with_child(
|
||||
form::input::Field::email()
|
||||
.with_name("email")
|
||||
.with_value(&data.email)
|
||||
.with_label(Lc::n("Email")),
|
||||
)
|
||||
.with_child(Button::submit(Lc::n("Join"))),
|
||||
)
|
||||
}
|
||||
|
||||
fn welcome_box(username: &str) -> Container {
|
||||
let username = username.trim().to_string();
|
||||
Container::new()
|
||||
.with_id("join")
|
||||
.with_child(Html::with(move |_| html! { p { "Welcome to the garden, " (username) "!" } }))
|
||||
}
|
||||
```
|
||||
|
||||
La ruta del envío valida y responde con uno u otro contenedor. Con HTMX, sólo el contenedor; sin
|
||||
JavaScript, una página entera con él. El error viaja como un mensaje del contexto, que muestra
|
||||
`Messages`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_htmx::prelude::*;
|
||||
# #[derive(Default, serde::Deserialize)]
|
||||
# struct JoinData { username: String }
|
||||
# fn validate(_: &JoinData) -> Option<Lc> { None }
|
||||
# fn join_box(_: &JoinData) -> Container { Container::new() }
|
||||
# fn welcome_box(_: &str) -> Container { Container::new() }
|
||||
async fn join(request: HttpRequest, web::Form(data): web::Form<JoinData>) -> Response {
|
||||
let error = validate(&data);
|
||||
let mut content = match error {
|
||||
Some(_) => join_box(&data),
|
||||
None => welcome_box(&data.username),
|
||||
};
|
||||
if request.is_htmx() {
|
||||
let mut cx = Context::new(request);
|
||||
if let Some(error) = error {
|
||||
cx.push_message(MessageLevel::Error, error);
|
||||
}
|
||||
return HtmxResponse::new(content.render(&mut cx).await).into_response();
|
||||
}
|
||||
let mut page = Page::new(request).with_child(content);
|
||||
if let Some(error) = error {
|
||||
page.context().push_message(MessageLevel::Error, error);
|
||||
}
|
||||
page.render().await.into_response()
|
||||
}
|
||||
```
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_htmx::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
const TAKEN: &[&str] = &["admin", "ana", "luke"];
|
||||
|
||||
struct JoinTheGarden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for JoinTheGarden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_htmx::Htmx]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(home))
|
||||
.route("/join", web::post(join))
|
||||
.route("/join/check", web::post(check_username))
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Default, Deserialize)]
|
||||
#[serde(default)]
|
||||
struct JoinData {
|
||||
username: String,
|
||||
email: String,
|
||||
}
|
||||
|
||||
fn validate(data: &JoinData) -> Option<Lc> {
|
||||
let username = data.username.trim();
|
||||
if username.chars().count() < 3 {
|
||||
Some(Lc::n("The username needs at least 3 characters."))
|
||||
} else if TAKEN.contains(&username) {
|
||||
Some(Lc::n("That username is already taken."))
|
||||
} else if !data.email.contains('@') {
|
||||
Some(Lc::n("Write a valid email."))
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
|
||||
fn username_field(data: &JoinData) -> form::input::Field {
|
||||
form::input::Field::text()
|
||||
.with_name("username")
|
||||
.with_value(&data.username)
|
||||
.with_label(Lc::n("Username"))
|
||||
.with_required(true)
|
||||
.with_prop(PropsOp::set(hx::POST, "/join/check"))
|
||||
.with_prop(PropsOp::set(hx::TRIGGER, "input delay:500ms"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#username-check"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::INNER_HTML))
|
||||
}
|
||||
|
||||
fn join_box(data: &JoinData) -> Container {
|
||||
Container::new().with_id("join").with_child(Messages::new()).with_child(
|
||||
Form::new()
|
||||
.with_action("/join")
|
||||
.with_prop(PropsOp::set(hx::POST, "/join"))
|
||||
.with_prop(PropsOp::set(hx::TARGET, "#join"))
|
||||
.with_prop(PropsOp::set(hx::SWAP, hx::swap::OUTER_HTML))
|
||||
.with_child(username_field(data))
|
||||
.with_child(Html::with(|_| html! { div id="username-check" {} }))
|
||||
.with_child(
|
||||
form::input::Field::email()
|
||||
.with_name("email")
|
||||
.with_value(&data.email)
|
||||
.with_label(Lc::n("Email")),
|
||||
)
|
||||
.with_child(Button::submit(Lc::n("Join"))),
|
||||
)
|
||||
}
|
||||
|
||||
fn welcome_box(username: &str) -> Container {
|
||||
let username = username.trim().to_string();
|
||||
Container::new()
|
||||
.with_id("join")
|
||||
.with_child(Html::with(move |_| html! { p { "Welcome to the garden, " (username) "!" } }))
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Join the garden"))
|
||||
.with_child(join_box(&JoinData::default()))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn check_username(request: HttpRequest, web::Form(data): web::Form<JoinData>) -> HtmxResponse {
|
||||
let username = data.username.trim();
|
||||
if username.is_empty() {
|
||||
return HtmxResponse::empty();
|
||||
}
|
||||
let mut badge = if TAKEN.contains(&username) {
|
||||
Badge::severe(Lc::n("Already taken"))
|
||||
} else {
|
||||
Badge::success(Lc::n("Available"))
|
||||
};
|
||||
HtmxResponse::new(badge.render(&mut Context::new(request)).await)
|
||||
}
|
||||
|
||||
async fn join(request: HttpRequest, web::Form(data): web::Form<JoinData>) -> Response {
|
||||
let error = validate(&data);
|
||||
let mut content = match error {
|
||||
Some(_) => join_box(&data),
|
||||
None => welcome_box(&data.username),
|
||||
};
|
||||
if request.is_htmx() {
|
||||
let mut cx = Context::new(request);
|
||||
if let Some(error) = error {
|
||||
cx.push_message(MessageLevel::Error, error);
|
||||
}
|
||||
return HtmxResponse::new(content.render(&mut cx).await).into_response();
|
||||
}
|
||||
let mut page = Page::new(request).with_child(content);
|
||||
if let Some(error) = error {
|
||||
page.context().push_message(MessageLevel::Error, error);
|
||||
}
|
||||
page.render().await.into_response()
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&JoinTheGarden).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
1. Escribe `ana` en el nombre de usuario y espera: aparece «Already taken». Cambia a `marta`:
|
||||
«Available».
|
||||
2. Envía el formulario con `ana`: el error aparece encima del formulario y lo escrito sigue ahí.
|
||||
3. Corrige el nombre, escribe un correo y envía: el formulario se sustituye por la bienvenida.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Editar en línea](htmx-edit.md): el mismo intercambio de formulario y vista, sobre un dato
|
||||
existente.
|
||||
- [Dirigir al navegador desde el servidor](htmx-responses.md): cambiar el destino de la respuesta
|
||||
según el resultado.
|
||||
136
doc/v0.6/es/src/how-to/layout.md
Normal file
136
doc/v0.6/es/src/how-to/layout.md
Normal file
|
|
@ -0,0 +1,136 @@
|
|||
# Maquetar con Flex y Grid
|
||||
|
||||
**Objetivo:** colocar componentes en filas, columnas o rejillas, y adaptarlos al tamaño de la
|
||||
pantalla, sin escribir CSS.
|
||||
|
||||
Para colocar componentes en filas, columnas o rejillas no hace falta escribir CSS: `Flex` y `Grid`
|
||||
generan las reglas por ti, y funcionan con cualquier tema.
|
||||
|
||||
## Flex: filas y columnas
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn item(t: &'static str) -> Html { Html::with(move |_| html! { div { (t) } }) }
|
||||
# fn f() -> Flex {
|
||||
Flex::new()
|
||||
.with_justify(flex::ContentJustify::SpaceBetween)
|
||||
.with_align(align::Items::Center)
|
||||
.with_gap(align::Gap::Both(UnitValue::RelRem(1.0)))
|
||||
.with_child(item("One"))
|
||||
.with_child(item("Two"))
|
||||
.with_child(item("Three"))
|
||||
# }
|
||||
```
|
||||
|
||||
| Método | Controla |
|
||||
|---|---|
|
||||
| `with_direction()` | `Row`, `RowReverse`, `Column` o `ColumnReverse` |
|
||||
| `with_justify()` | Reparto en el eje principal: `Start`, `Center`, `End`, `SpaceBetween`... |
|
||||
| `with_align()` | Alineación en el eje transversal: `Start`, `Center`, `End`, `Stretch`, `Baseline` |
|
||||
| `with_wrap()` | Si los elementos saltan de línea |
|
||||
| `with_gap()` | Separación entre elementos |
|
||||
|
||||
Cada hijo puede ajustarse por separado con `FlexItem`, que se pasa a su `with_prop()`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Flex {
|
||||
Flex::new()
|
||||
.with_child(Block::new().with_title(Lc::n("Menu")))
|
||||
.with_child(
|
||||
Block::new()
|
||||
.with_title(Lc::n("Content"))
|
||||
.with_prop(FlexItem::new().with_grow(flex::ItemGrow::Is1)),
|
||||
)
|
||||
.with_child(
|
||||
Block::new()
|
||||
.with_title(Lc::n("Help"))
|
||||
.with_prop(FlexItem::push_end()),
|
||||
)
|
||||
# }
|
||||
```
|
||||
|
||||
`FlexItem::push_end()` empuja el elemento al final de la fila. Es la forma habitual de alinear a
|
||||
la derecha el último grupo de un menú.
|
||||
|
||||
## Grid: rejillas
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn item(t: &'static str) -> Html { Html::with(move |_| html! { div { (t) } }) }
|
||||
# fn f() -> Grid {
|
||||
Grid::new()
|
||||
.with_columns(grid::Tracks::repeat(3, grid::AxisTrack::Fraction(1.0)))
|
||||
.with_gap(align::Gap::Both(UnitValue::RelRem(1.0)))
|
||||
.with_child(item("A"))
|
||||
.with_child(item("B"))
|
||||
.with_child(item("C"))
|
||||
.with_child(item("D"))
|
||||
# }
|
||||
```
|
||||
|
||||
Tres columnas iguales (`1fr` cada una). Las pistas se combinan a voluntad:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Grid {
|
||||
// A fixed 240 px column and another one that takes the rest.
|
||||
Grid::new().with_columns(
|
||||
grid::Tracks::new()
|
||||
.with_track(grid::AxisTrack::Fixed(UnitValue::Px(240)))
|
||||
.with_track(grid::AxisTrack::Fraction(1.0)),
|
||||
)
|
||||
# }
|
||||
```
|
||||
|
||||
Un hijo puede ocupar varias celdas con `GridItem`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Block {
|
||||
Block::new()
|
||||
.with_title(Lc::n("Featured"))
|
||||
.with_prop(GridItem::new().with_column(grid::ItemPlacement::Span(2)))
|
||||
# }
|
||||
```
|
||||
|
||||
## Diseño *responsive*
|
||||
|
||||
Casi todos los métodos tienen una variante `_at()` que se aplica **a partir de** un punto de
|
||||
corte (el diseño es *mobile-first*: lo que no lleva `_at()` vale para todos los tamaños):
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Flex {
|
||||
// A column on mobile; a row from medium screens on.
|
||||
Flex::new()
|
||||
.with_direction(flex::Direction::Column)
|
||||
.with_direction_at(Breakpoint::Md, flex::Direction::Row)
|
||||
# }
|
||||
```
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Grid {
|
||||
// One column on mobile, two on tablets and four on desktop.
|
||||
Grid::new()
|
||||
.with_columns(grid::Tracks::repeat(1, grid::AxisTrack::Fraction(1.0)))
|
||||
.with_columns_at(Breakpoint::Md, grid::Tracks::repeat(2, grid::AxisTrack::Fraction(1.0)))
|
||||
.with_columns_at(Breakpoint::Xl, grid::Tracks::repeat(4, grid::AxisTrack::Fraction(1.0)))
|
||||
# }
|
||||
```
|
||||
|
||||
Los puntos de corte son `Xs`, `Sm`, `Md`, `Lg`, `Xl`, `Xxl` y `Xxxl`. Sus anchos los decide el
|
||||
tema; por defecto son 576, 768, 992, 1200, 1400 y 1920 píxeles a partir de `Sm` (`Xs` no tiene
|
||||
mínimo).
|
||||
|
||||
## Comprueba
|
||||
|
||||
Estrecha la ventana del navegador: los elementos cambian de disposición al cruzar cada punto de
|
||||
corte. En las herramientas de desarrollo verás que cada `_at()` se ha convertido en una regla
|
||||
`@media`.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Añadir navegación](navigation.md).
|
||||
- [Crear un tema](themes.md): cómo un tema fija los anchos de los puntos de corte.
|
||||
150
doc/v0.6/es/src/how-to/localization.md
Normal file
150
doc/v0.6/es/src/how-to/localization.md
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
# Traducir la aplicación
|
||||
|
||||
**Objetivo:** mostrar cada texto en el idioma del visitante, con plurales correctos, y formatear
|
||||
fechas y horas según su idioma y su zona horaria.
|
||||
|
||||
PageTop traduce con [Fluent](https://projectfluent.org), el sistema de Mozilla: cada idioma tiene
|
||||
sus archivos `.ftl` con pares `key = text`, y las traducciones se integran en el binario al
|
||||
compilar.
|
||||
|
||||
## 1. Crea los archivos de traducción
|
||||
|
||||
Por defecto viven en `src/locale/`, en un directorio por idioma:
|
||||
|
||||
```text
|
||||
src/locale/
|
||||
├── en-US/
|
||||
│ └── app.ftl
|
||||
└── es-ES/
|
||||
└── app.ftl
|
||||
```
|
||||
|
||||
```text
|
||||
# src/locale/es-ES/app.ftl
|
||||
greeting = ¡Hola!
|
||||
welcome = Te damos la bienvenida, { $name }.
|
||||
notices = { $total ->
|
||||
[one] Tienes un aviso
|
||||
*[other] Tienes { $total } avisos
|
||||
}
|
||||
```
|
||||
|
||||
```text
|
||||
# src/locale/en-US/app.ftl
|
||||
greeting = Hello!
|
||||
welcome = Welcome, { $name }.
|
||||
notices = { $total ->
|
||||
[one] You have one notice
|
||||
*[other] You have { $total } notices
|
||||
}
|
||||
```
|
||||
|
||||
Fluent resuelve los plurales y las variantes de cada idioma en el propio archivo, sin lógica en el
|
||||
código.
|
||||
|
||||
## 2. Úsalos en el código
|
||||
|
||||
Declara el conjunto de traducciones una vez con `include_locales!`:
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
include_locales!(LOCALES_APP);
|
||||
```
|
||||
|
||||
Y crea textos con `Lc`:
|
||||
|
||||
| Constructor | Qué representa |
|
||||
|---|---|
|
||||
| `Lc::t("key", &LOCALES_APP)` | Traducción de tus archivos |
|
||||
| `Lc::l("key")` | Traducción de los archivos de PageTop |
|
||||
| `Lc::n("text")` | Texto literal, sin traducir |
|
||||
| `Lc::none()` | Ningún texto |
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
include_locales!(LOCALES_APP);
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::t("greeting", &LOCALES_APP))
|
||||
.with_child(Html::with(|cx| {
|
||||
let welcome = Lc::t("welcome", &LOCALES_APP).with_arg("name", "Ana");
|
||||
let notices = Lc::t("notices", &LOCALES_APP).with_number("total", 3);
|
||||
html! {
|
||||
h1 { (welcome.using(cx)) }
|
||||
p { (notices.using(cx)) }
|
||||
}
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
- `with_arg()` rellena una variable; `with_number()` la rellena con un número, para que Fluent
|
||||
elija el plural correcto.
|
||||
- `using(cx)` devuelve el texto listo para insertarlo como **contenido** en `html!`.
|
||||
- `lookup(cx)` devuelve `Option<String>`. Úsalo para los **atributos** (`title`, `alt`,
|
||||
`placeholder`...), donde el texto se escapa como cualquier otro valor:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# include_locales!(LOCALES_APP);
|
||||
# fn f() -> Html {
|
||||
Html::with(|cx| {
|
||||
let title = Lc::t("greeting", &LOCALES_APP).lookup(cx);
|
||||
html! { button title=[title] { "?" } }
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
Los componentes reciben `Lc`, no cadenas: así cada visitante ve el texto en su idioma.
|
||||
|
||||
## 3. Decide qué idioma ve cada visitante
|
||||
|
||||
Por defecto, PageTop decide el idioma de cada petición en este orden:
|
||||
|
||||
1. El parámetro `?lang=` de la URL.
|
||||
2. El idioma preferido del usuario, si ha iniciado sesión y lo tiene.
|
||||
3. El idioma de la configuración (`[app] language`).
|
||||
4. La cabecera `Accept-Language` del navegador.
|
||||
5. El idioma de respaldo, `en-US`.
|
||||
|
||||
La clave `lang_negotiation` de `[app]` cambia la estrategia: `"NoQuery"` ignora `?lang=` y
|
||||
`"ConfigOnly"` usa sólo el idioma configurado. Los enlaces internos conservan `?lang=` solos (ver
|
||||
[Navegación](navigation.md#enlaces-que-conservan-el-idioma)).
|
||||
|
||||
PageTop trae sus propios textos en español (`es-ES`) e inglés (`en-US` y `en-GB`).
|
||||
|
||||
## 4. Formatea fechas y horas
|
||||
|
||||
El contexto formatea fechas con las convenciones del idioma y la zona horaria del visitante:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f() -> Html {
|
||||
Html::with(|cx| {
|
||||
let date = NaiveDate::from_ymd_opt(2026, 10, 12).unwrap();
|
||||
let now = Utc::now();
|
||||
html! {
|
||||
p { "Published on " (cx.format_date(date, DateFormat::Long)) }
|
||||
p { "Updated: " (cx.format_datetime(now, DateFormat::Short, TimeFormat::Short)) }
|
||||
}
|
||||
})
|
||||
# }
|
||||
```
|
||||
|
||||
Los formatos son `Short`, `Medium`, `Long`, `Iso` y `Custom("...")`. La zona horaria se configura
|
||||
con `[app] timezone`.
|
||||
|
||||
## Comprueba
|
||||
|
||||
Abre una página con `?lang=es` y con `?lang=en`: los textos cambian, y los plurales cambian con el
|
||||
número. Si a un idioma le falta una clave, se usa la del idioma de respaldo, `en-US`; si no existe
|
||||
en ninguno, el texto sale vacío. Una [prueba](testing.md) que busque los textos en cada idioma lo
|
||||
detecta antes que los usuarios.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Añadir navegación](navigation.md#enlaces-que-conservan-el-idioma): enlaces que conservan el
|
||||
idioma elegido.
|
||||
- [Probar rutas y componentes](testing.md): comprobar las traducciones en una prueba.
|
||||
101
doc/v0.6/es/src/how-to/logging.md
Normal file
101
doc/v0.6/es/src/how-to/logging.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
# Registrar trazas
|
||||
|
||||
**Objetivo:** dejar constancia de lo que pasa en la aplicación, con el nivel de detalle adecuado
|
||||
en cada entorno, por el terminal o en archivos con rotación.
|
||||
|
||||
PageTop usa [tracing](https://docs.rs/tracing), y lo expone en el módulo `trace` del preludio.
|
||||
|
||||
## 1. Escribe trazas
|
||||
|
||||
Hay una macro por nivel, de más a menos grave: `error!`, `warn!`, `info!`, `debug!` y `trace!`.
|
||||
Admiten el formato de `format!`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f(order: u32, error: &str) {
|
||||
trace::info!("Order {order} received");
|
||||
trace::warn!("Low stock for order {order}");
|
||||
trace::error!("Could not charge order {order}: {error}");
|
||||
# }
|
||||
```
|
||||
|
||||
Y también **campos** con nombre, que en formato JSON salen como claves propias y se pueden filtrar
|
||||
y buscar:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn f(order: u32, total: f64) {
|
||||
trace::info!(order, total, "Order received");
|
||||
# }
|
||||
```
|
||||
|
||||
## 2. Agrupa las trazas de una operación
|
||||
|
||||
Un *span* (intervalo) agrupa todo lo que ocurre durante una operación. Las trazas emitidas dentro
|
||||
llevan sus campos, aunque vengan de otras funciones:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# fn charge() {}
|
||||
# fn send_receipt() {}
|
||||
# fn f(order: u32) {
|
||||
let span = trace::info_span!("checkout", order);
|
||||
let _entered = span.enter();
|
||||
trace::info!("Charging"); // checkout{order=42}: Charging
|
||||
charge();
|
||||
send_receipt();
|
||||
# }
|
||||
```
|
||||
|
||||
No mantengas un `span.enter()` abierto a través de un `.await`: en código asíncrono, la tarea
|
||||
puede continuar en otro hilo.
|
||||
|
||||
## 3. Elige qué se registra
|
||||
|
||||
La sección `[log]` decide el nivel, la salida y el formato:
|
||||
|
||||
```toml
|
||||
[log]
|
||||
tracing = "Info,sqlx=Warn" # General level and levels per module.
|
||||
rolling = "Daily" # Stdout, Daily, Hourly, Minutely or Endless.
|
||||
path = "log" # Directory of the trace files.
|
||||
format = "Json" # Full, Compact, Pretty or Json.
|
||||
```
|
||||
|
||||
- **`tracing`** fija el nivel general y, separados por comas, niveles por módulo. `"Info,sqlx=Warn"`
|
||||
registra todo desde `info`, salvo las sentencias SQL, que sólo aparecen si fallan.
|
||||
- **`rolling`**: con `"Stdout"` (por defecto) las trazas salen por el terminal; con `"Daily"`,
|
||||
`"Hourly"` o `"Minutely"` se escriben en archivos que rotan con esa frecuencia, y con
|
||||
`"Endless"` en un único archivo.
|
||||
- **`format`**: `"Full"` para leer en el terminal, `"Json"` para que lo procese otra herramienta.
|
||||
|
||||
Un filtro mal escrito no detiene la aplicación: se usa `"Info"` y se avisa al arrancar.
|
||||
|
||||
## 4. Un nivel por entorno
|
||||
|
||||
Con la [cascada de configuración](configuration.md), cada entorno tiene su nivel sin tocar el
|
||||
código:
|
||||
|
||||
```toml
|
||||
# config/common.toml
|
||||
[log]
|
||||
tracing = "Info,sqlx=Warn"
|
||||
```
|
||||
|
||||
```toml
|
||||
# config/local.toml (your machine only, not versioned)
|
||||
[log]
|
||||
tracing = "Debug,pagetop=Info"
|
||||
format = "Pretty"
|
||||
```
|
||||
|
||||
## Comprueba
|
||||
|
||||
Arranca con `rolling = "Daily"`: aparece el directorio `log/` con un archivo `tracing.log.<fecha>`.
|
||||
Las trazas se escriben en segundo plano, sin frenar las peticiones, y PageTop vuelca las pendientes
|
||||
al detenerse con `Ctrl+C` o `SIGTERM`.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Desplegar en producción](deployment.md).
|
||||
- [Opciones de configuración](../reference/configuration.md#log): todas las claves de `[log]`.
|
||||
578
doc/v0.6/es/src/how-to/mail.md
Normal file
578
doc/v0.6/es/src/how-to/mail.md
Normal file
|
|
@ -0,0 +1,578 @@
|
|||
# Enviar correo electrónico
|
||||
|
||||
**Objetivo:** enviar correos desde la aplicación, en texto y HTML, con adjuntos, traducidos al
|
||||
idioma de cada destinatario y con el mismo aspecto que los de las demás extensiones, sin enviar
|
||||
nunca correo real por error mientras desarrollas.
|
||||
|
||||
Lo aporta la extensión `pagetop-mail`. La configuración decide **cómo** se entregan los correos
|
||||
(servidor SMTP, *sendmail*, archivos, trazas o memoria), así que el código que los envía es el
|
||||
mismo en desarrollo, en las pruebas y en producción.
|
||||
|
||||
## 1. Añade la dependencia
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
pagetop-mail = { git = "https://git.cillero.es/manuelcillero/pagetop" }
|
||||
```
|
||||
|
||||
Y declara `pagetop_mail::Mail` en `dependencies()` de la extensión que envía correos:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
pub struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_mail::Mail]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Configura el envío
|
||||
|
||||
Sin configurar nada, los correos **no se envían**: se escriben en las trazas, con el remitente, los
|
||||
destinatarios, el asunto y el texto. Es lo que quieres mientras desarrollas. Para enviarlos de
|
||||
verdad, configura la sección `[mail]` con el transporte, el remitente y la URL pública de la
|
||||
aplicación, que forma los enlaces de los correos (ver el paso 5):
|
||||
|
||||
```toml
|
||||
# config/production.toml
|
||||
[mail]
|
||||
transport = "smtp"
|
||||
from = "Community garden <no-reply@example.com>"
|
||||
base_url = "https://garden.example.com"
|
||||
|
||||
[mail.smtp]
|
||||
host = "smtp.example.com"
|
||||
username = "no-reply@example.com"
|
||||
```
|
||||
|
||||
La contraseña no va en un archivo versionado: ponla en `config/local.toml` o en la variable de
|
||||
entorno `PAGETOP_MAIL__SMTP__PASSWORD`. Por defecto la conexión exige `STARTTLS` en el puerto 587;
|
||||
`security = "tls"` usa el 465.
|
||||
|
||||
Para ver los correos tal como llegan sin enviarlos a nadie, usa en desarrollo un servidor como
|
||||
[Mailpit](https://mailpit.axllent.org), que los recoge y los muestra en el navegador:
|
||||
|
||||
```toml
|
||||
# config/local.toml
|
||||
[mail]
|
||||
transport = "smtp"
|
||||
|
||||
[mail.smtp]
|
||||
host = "localhost"
|
||||
port = 1025
|
||||
security = "none"
|
||||
```
|
||||
|
||||
Con `transport = "file"`, cada correo se guarda como un archivo `.eml` en el directorio `mail/`,
|
||||
que abre cualquier cliente de correo. Y en un entorno de pruebas con datos reales,
|
||||
`redirect_to = "qa@example.com"` entrega todos los correos sólo a esa dirección. Los ajustes no
|
||||
válidos detienen el arranque con un mensaje que indica el problema.
|
||||
|
||||
## 3. Envía un correo
|
||||
|
||||
Un correo se compone con `Email`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
use pagetop_mail::prelude::*;
|
||||
|
||||
async fn confirm_plot(address: String) -> Result<(), MailError> {
|
||||
Email::new()
|
||||
.with_to(address)
|
||||
.with_subject("Your plot is booked")
|
||||
.with_html(html! {
|
||||
p { "Your plot " strong { "B-12" } " is booked for the whole season." }
|
||||
})
|
||||
.send()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
Las direcciones admiten la forma `"Ana Pérez <ana@example.com>"`, y `with_cc()`, `with_bcc()` y
|
||||
`with_reply_to()` completan los destinatarios; el remitente es el de `mail.from` salvo que indiques
|
||||
otro con `with_from()`. Si el correo sólo tiene HTML, al enviarlo se genera su versión en texto
|
||||
plano; escríbela tú con `with_text()` sólo si la generada no queda bien.
|
||||
|
||||
Hay dos formas de enviarlo:
|
||||
|
||||
- **`send().await`** espera a que el correo se entregue y devuelve el error si falla. Úsalo cuando
|
||||
necesitas saberlo para responder.
|
||||
- **`send_later()`** lo entrega en segundo plano y vuelve enseguida; si falla, lo registra en las
|
||||
trazas. Es lo indicado en una petición del usuario: la respuesta no espera al servidor de
|
||||
correo, y su tiempo no revela nada (por ejemplo, si existe la cuenta para la que se pide
|
||||
recuperar la contraseña).
|
||||
|
||||
## 4. Escribe una plantilla traducida
|
||||
|
||||
Para que el mismo correo llegue a cada destinatario en su idioma, defínelo como un tipo que
|
||||
implementa `MailTemplate`. Sus métodos reciben un `Context` con el idioma del destinatario, y los
|
||||
textos se escriben con `Lc`, igual que en un componente:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_mail::prelude::*;
|
||||
include_locales!(LOCALES_APP);
|
||||
|
||||
struct HarvestNotice {
|
||||
name: String,
|
||||
}
|
||||
|
||||
impl MailTemplate for HarvestNotice {
|
||||
fn subject(&self, cx: &Context) -> String {
|
||||
Lc::t("harvest-subject", &LOCALES_APP).lookup(cx).unwrap_or_default()
|
||||
}
|
||||
|
||||
fn html(&self, cx: &Context) -> Option<Markup> {
|
||||
let greeting = Lc::t("harvest-greeting", &LOCALES_APP).with_arg("name", self.name.clone());
|
||||
Some(html! {
|
||||
p { (greeting.using(cx)) }
|
||||
p { (Lc::t("harvest-ready", &LOCALES_APP).using(cx)) }
|
||||
p {
|
||||
a href=(absolute_url("/harvest")) {
|
||||
(Lc::t("harvest-link", &LOCALES_APP).using(cx))
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Con sus traducciones en `src/locale/en-US/app.ftl`:
|
||||
|
||||
```ftl
|
||||
harvest-subject = The tomatoes are ready to pick
|
||||
harvest-greeting = Hello, { $name }:
|
||||
harvest-ready = The tomatoes in the community garden are ripe. Come and pick your share this week.
|
||||
harvest-link = See the harvest calendar
|
||||
```
|
||||
|
||||
`Email::from_template()` crea el correo con el asunto y el contenido de la plantilla. El contexto
|
||||
decide el idioma. Si el destinatario es quien hace la petición (por ejemplo, al apuntarse a un
|
||||
aviso), usa el de la petición. Si es otra persona, crea uno con su idioma, guardado junto a su
|
||||
dirección; si no es un idioma disponible, el correo sale en el idioma por defecto de la aplicación:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_mail::prelude::*;
|
||||
# struct HarvestNotice { name: String }
|
||||
# impl MailTemplate for HarvestNotice {
|
||||
# fn subject(&self, _cx: &Context) -> String { String::new() }
|
||||
# }
|
||||
async fn notify_gardener(name: String, email: String, language: String) -> Result<(), MailError> {
|
||||
let cx = Context::default().with_langid(&Locale::resolve(language));
|
||||
Email::from_template(&HarvestNotice { name }, &cx)
|
||||
.with_to(email)
|
||||
.send()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Usa enlaces absolutos
|
||||
|
||||
Un enlace de un correo se abre fuera de la aplicación, así que debe ser absoluto. `absolute_url()`
|
||||
antepone a la ruta la URL pública de `mail.base_url`, como en la plantilla anterior. Si no la
|
||||
configuras, usa la dirección y el puerto de escucha (`http://localhost:8080`), que sólo sirve en
|
||||
desarrollo.
|
||||
|
||||
La URL no se deduce de la petición: la cabecera `Host` la elige el cliente, y un atacante podría
|
||||
conseguir que el enlace de un correo de recuperación de contraseña apuntara a su propio servidor.
|
||||
|
||||
## 6. Adjunta archivos
|
||||
|
||||
`Attachment` crea un adjunto con un contenido en memoria o leyendo un archivo, y deduce su tipo del
|
||||
nombre. Con `with_content_id()` el adjunto se incrusta en el HTML, que lo muestra con `cid:`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_mail::prelude::*;
|
||||
async fn send_report(address: String, logo_png: Vec<u8>) -> Result<(), MailError> {
|
||||
Email::new()
|
||||
.with_to(address)
|
||||
.with_subject("October harvest report")
|
||||
.with_html(html! {
|
||||
img src="cid:logo" alt="Community garden";
|
||||
p { "The report of the month is attached." }
|
||||
})
|
||||
.with_attachment(Attachment::new("logo.png", logo_png).with_content_id("logo"))
|
||||
.with_attachment(Attachment::from_path("reports/october.pdf").await?)
|
||||
.send()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Dale tu imagen a los correos
|
||||
|
||||
El HTML de un correo es sólo su contenido: al enviarlo se envuelve en un diseño común, sobrio y
|
||||
neutro, con el nombre de la aplicación al pie. Para dar tu propia imagen a **todos** los correos,
|
||||
también a los que envían otras extensiones como `pagetop-user`, registra la acción
|
||||
`RenderMailLayout`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_mail::prelude::*;
|
||||
fn garden_layout(cx: &Context, email: &Email, content: &Markup) -> Markup {
|
||||
html! {
|
||||
(DOCTYPE)
|
||||
html lang=(cx.langid().to_string()) {
|
||||
head {
|
||||
meta charset="utf-8";
|
||||
title { (email.subject()) }
|
||||
}
|
||||
body style="margin: 0; padding: 24px; background: #f0f5ec; font-family: sans-serif;" {
|
||||
div style="max-width: 600px; margin: 0 auto; padding: 24px; background: #fff;" {
|
||||
(content)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pub struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_mail::Mail]
|
||||
}
|
||||
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![RenderMailLayout::new(garden_layout)]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Si varias extensiones registran esta acción, se aplica sólo la de menor peso
|
||||
(`RenderMailLayout::new(..).with_weight(..)`). Los clientes de correo ignoran las hojas de estilo
|
||||
externas, y muchos también los estilos del `<head>`: escribe los estilos en línea, con `style`. Un
|
||||
correo concreto puede saltarse el diseño con `with_html_document()`, que envía el documento tal
|
||||
cual.
|
||||
|
||||
## 8. Revisa los correos en el navegador
|
||||
|
||||
Para ver cómo queda un correo sin enviarlo, declara una vista previa con datos de ejemplo:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_mail::prelude::*;
|
||||
# struct HarvestNotice { name: String }
|
||||
# impl MailTemplate for HarvestNotice {
|
||||
# fn subject(&self, _cx: &Context) -> String { String::new() }
|
||||
# }
|
||||
fn harvest_preview(cx: &Context) -> Email {
|
||||
let notice = HarvestNotice { name: "Ana".to_string() };
|
||||
Email::from_template(¬ice, cx).with_to("ana@example.com")
|
||||
}
|
||||
|
||||
fn declare_previews(previews: &mut MailPreviews) {
|
||||
previews.add("garden.harvest", Lc::n("Harvest notice"), harvest_preview);
|
||||
}
|
||||
|
||||
pub struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_mail::Mail]
|
||||
}
|
||||
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![DeclareMailPreviews::new(declare_previews)]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Activa las vistas previas sólo en desarrollo, porque muestran las plantillas a quien conozca la
|
||||
ruta:
|
||||
|
||||
```toml
|
||||
# config/local.toml
|
||||
[mail]
|
||||
previews = true
|
||||
```
|
||||
|
||||
`/mail/preview` lista los correos declarados por todas las extensiones, y cada uno se muestra
|
||||
completo, con el diseño común, las cabeceras, el texto plano y los adjuntos. Añade `?lang=es` para
|
||||
verlo en otro idioma.
|
||||
|
||||
## 9. Guarda los correos en una cola
|
||||
|
||||
Sin más, un correo de `send_later()` se pierde si la aplicación se detiene antes de entregarlo, y
|
||||
no se reintenta si el servidor falla. Con la *feature* `queue`, los correos se guardan en la base
|
||||
de datos de `pagetop-seaorm` y se reintentan:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
pagetop-mail = { git = "https://git.cillero.es/manuelcillero/pagetop", features = ["queue"] }
|
||||
pagetop-seaorm = { git = "https://git.cillero.es/manuelcillero/pagetop", features = ["sqlite"] }
|
||||
```
|
||||
|
||||
La cola crea su tabla al arrancar, en la base de datos de `[database]`. Con ella:
|
||||
|
||||
- **`send_later()`** guarda el correo y lo intenta enseguida (salvo con `transport = "log"`, que
|
||||
lo escribe directamente en las trazas). Si el fallo es temporal, queda en la cola y se reintenta
|
||||
más tarde, también después de un reinicio, con una espera que se duplica en cada intento. Un
|
||||
rechazo definitivo del servidor o el último intento lo dejan como fallido.
|
||||
- **`queue()`** sólo lo guarda: el trabajo `mail.queue` de `pagetop-cron` envía los pendientes por
|
||||
lotes, uno tras otro. Es lo indicado para los envíos masivos, que así no saturan el equipo ni el
|
||||
servidor de correo:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_mail::prelude::*;
|
||||
async fn announce_closure(addresses: Vec<String>) -> Result<(), MailError> {
|
||||
for address in addresses {
|
||||
Email::new()
|
||||
.with_to(address)
|
||||
.with_subject("The garden closes on Saturday")
|
||||
.with_text("The garden will be closed on Saturday for the water works.")
|
||||
.queue()
|
||||
.await?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
El tamaño de los lotes y los reintentos se ajustan en
|
||||
[`[mail.queue]`](../reference/configuration.md#mailqueue), y el ritmo en la programación del
|
||||
trabajo:
|
||||
|
||||
```toml
|
||||
[cron.jobs."mail.queue"]
|
||||
schedule = "@delay 30s" # 30 s after each batch ends (1 minute by default).
|
||||
```
|
||||
|
||||
La cola guarda los mensajes completos y sin cifrar hasta entregarlos: pueden contener datos
|
||||
personales y enlaces de un solo uso, también en las copias de seguridad de la base de datos.
|
||||
|
||||
## El ejemplo completo
|
||||
|
||||
Un formulario en `/harvest` donde cada visitante pide el aviso de la cosecha, que recibe por
|
||||
correo en su idioma:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_mail::prelude::*;
|
||||
use serde::Deserialize;
|
||||
|
||||
include_locales!(LOCALES_APP);
|
||||
|
||||
struct HarvestNotice {
|
||||
name: String,
|
||||
}
|
||||
|
||||
impl MailTemplate for HarvestNotice {
|
||||
fn subject(&self, cx: &Context) -> String {
|
||||
Lc::t("harvest-subject", &LOCALES_APP).lookup(cx).unwrap_or_default()
|
||||
}
|
||||
|
||||
fn html(&self, cx: &Context) -> Option<Markup> {
|
||||
let greeting = Lc::t("harvest-greeting", &LOCALES_APP).with_arg("name", self.name.clone());
|
||||
Some(html! {
|
||||
p { (greeting.using(cx)) }
|
||||
p { (Lc::t("harvest-ready", &LOCALES_APP).using(cx)) }
|
||||
p {
|
||||
a href=(absolute_url("/harvest")) {
|
||||
(Lc::t("harvest-link", &LOCALES_APP).using(cx))
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
fn harvest_preview(cx: &Context) -> Email {
|
||||
let notice = HarvestNotice { name: "Ana".to_string() };
|
||||
Email::from_template(¬ice, cx).with_to("ana@example.com")
|
||||
}
|
||||
|
||||
fn declare_previews(previews: &mut MailPreviews) {
|
||||
previews.add("garden.harvest", Lc::n("Harvest notice"), harvest_preview);
|
||||
}
|
||||
|
||||
struct Garden;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Garden {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_mail::Mail]
|
||||
}
|
||||
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![DeclareMailPreviews::new(declare_previews)]
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router.route("/harvest", web::get(show).post(notify))
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct Gardener {
|
||||
name: String,
|
||||
email: String,
|
||||
}
|
||||
|
||||
fn notice_form() -> Form {
|
||||
Form::new()
|
||||
.with_action("/harvest")
|
||||
.with_method(form::Method::Post)
|
||||
.with_child(
|
||||
form::input::Field::text()
|
||||
.with_name("name")
|
||||
.with_label(Lc::n("Name"))
|
||||
.with_required(true),
|
||||
)
|
||||
.with_child(
|
||||
form::input::Field::email()
|
||||
.with_name("email")
|
||||
.with_label(Lc::n("Email"))
|
||||
.with_required(true),
|
||||
)
|
||||
.with_child(Button::submit(Lc::n("Send me the notice")))
|
||||
}
|
||||
|
||||
async fn show(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Harvest"))
|
||||
.with_child(notice_form())
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
async fn notify(
|
||||
request: HttpRequest,
|
||||
web::Form(gardener): web::Form<Gardener>,
|
||||
) -> Result<Response, ErrorPage> {
|
||||
// The notice goes in the language of the visitor who asks for it.
|
||||
let cx = Context::new(request.clone());
|
||||
let notice = HarvestNotice { name: gardener.name };
|
||||
let sent = Email::from_template(¬ice, &cx)
|
||||
.with_to(gardener.email)
|
||||
.send()
|
||||
.await;
|
||||
if let Err(err) = sent {
|
||||
trace::warn!("Harvest notice not sent: {err}");
|
||||
let mut page = Page::new(request)
|
||||
.with_title(Lc::n("Harvest"))
|
||||
.with_child(notice_form());
|
||||
page.context().push_message(
|
||||
MessageLevel::Error,
|
||||
Lc::n("The notice could not be sent. Check the address and try again."),
|
||||
);
|
||||
return page.render().await.map(IntoResponse::into_response);
|
||||
}
|
||||
Ok(Redirect::see_other(cx.route("/harvest")).with_message(
|
||||
&cx,
|
||||
MessageLevel::Info,
|
||||
Lc::n("We have sent you the notice. Check your inbox."),
|
||||
))
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&Garden).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
El ejemplo usa `send().await` para avisar en el formulario si la dirección no es válida o el
|
||||
servidor la rechaza. Si prefieres no hacer esperar al visitante, cambia `send().await` por
|
||||
`send_later()` y avisa siempre del envío: los fallos quedarán en las trazas.
|
||||
|
||||
## Comprueba
|
||||
|
||||
Arranca con `cargo run`, abre <http://localhost:8080/harvest> y envía el formulario: la página
|
||||
confirma el envío y el terminal muestra el correo, porque sin configurar `[mail]` se escribe en las
|
||||
trazas. Con `previews = true` en `config/local.toml`, <http://localhost:8080/mail/preview> lo
|
||||
muestra con su diseño.
|
||||
|
||||
En las pruebas, el transporte `memory` guarda los correos en lugar de enviarlos, y
|
||||
`pagetop_mail::outbox` los recoge. Configúralo en `config/test.toml` (ve [Usa otra configuración
|
||||
para las pruebas](testing.md#5-usa-otra-configuración-para-las-pruebas)):
|
||||
|
||||
```toml
|
||||
# config/test.toml
|
||||
[mail]
|
||||
transport = "memory"
|
||||
from = "Community garden <garden@example.com>"
|
||||
base_url = "https://garden.example.com"
|
||||
```
|
||||
|
||||
```rust
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_mail::prelude::*;
|
||||
# use serde::Deserialize;
|
||||
# include_locales!(LOCALES_APP);
|
||||
# struct HarvestNotice { name: String }
|
||||
# impl MailTemplate for HarvestNotice {
|
||||
# fn subject(&self, cx: &Context) -> String {
|
||||
# Lc::t("harvest-subject", &LOCALES_APP).lookup(cx).unwrap_or_default()
|
||||
# }
|
||||
# fn html(&self, cx: &Context) -> Option<Markup> {
|
||||
# let greeting = Lc::t("harvest-greeting", &LOCALES_APP).with_arg("name", self.name.clone());
|
||||
# let link = Lc::t("harvest-link", &LOCALES_APP);
|
||||
# Some(html! {
|
||||
# p { (greeting.using(cx)) }
|
||||
# p { a href=(absolute_url("/harvest")) { (link.using(cx)) } }
|
||||
# })
|
||||
# }
|
||||
# }
|
||||
# struct Garden;
|
||||
# #[async_trait]
|
||||
# impl Extension for Garden {
|
||||
# fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
# vec![&pagetop_mail::Mail]
|
||||
# }
|
||||
# fn configure_router(&self, router: Router) -> Router {
|
||||
# router.route("/harvest", web::post(notify))
|
||||
# }
|
||||
# }
|
||||
# #[derive(Deserialize)]
|
||||
# struct Gardener { name: String, email: String }
|
||||
# async fn notify(
|
||||
# request: HttpRequest,
|
||||
# web::Form(gardener): web::Form<Gardener>,
|
||||
# ) -> Result<Response, ErrorPage> {
|
||||
# let cx = Context::new(request.clone());
|
||||
# Email::from_template(&HarvestNotice { name: gardener.name }, &cx)
|
||||
# .with_to(gardener.email)
|
||||
# .send()
|
||||
# .await
|
||||
# .map_err(|_| ErrorPage::InternalError(Some(request)))?;
|
||||
# Ok(Redirect::see_other(cx.route("/harvest")))
|
||||
# }
|
||||
use pagetop_mail::outbox;
|
||||