pagetop-website/doc/v0.6/es/src/how-to/forms.md
Manuel Cillero 4e007feec8 📝 Doc cron, mail queue, CSRF and flash messages
Add the scheduled tasks guide, environment variable overrides, the
[mail] and [cron] references, CSRF protection without tokens, flash
messages after redirects and the username policies of pagetop-user.
Update the framework comparison with Poem and Topcoat.
2026-11-02 14:46:28 +01:00

8 KiB

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.

# 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:

# 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):

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:

#[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:

# 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:
[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