Trait rocket::request::FromForm [−] [src]

pub trait FromForm<'f>: Sized {
    type Error;
    fn from_form(
        it: &mut FormItems<'f>, 
        strict: bool
    ) -> Result<Self, Self::Error>;
}

Trait to create an instance of some type from an HTTP form. Form requires its generic type to implement this trait.

Deriving

This trait can be automatically derived via the rocket_codegen plugin. When deriving FromForm, every field in the structure must implement FromFormValue. Rocket validates each field in the structure by calling its FromFormValue implemention. You may wish to implement FromFormValue for your own types for custom, automatic validation.

#![feature(plugin, custom_derive)]
#![plugin(rocket_codegen)]

extern crate rocket;

#[derive(FromForm)]
struct TodoTask {
    description: String,
    completed: bool
}

Data Guard

Types that implement FromForm can be parsed directly from incoming form data via the data parameter and Form type.

#[post("/submit", data = "<task>")]
fn submit_task(task: Form<TodoTask>) -> String {
    format!("New task: {}", task.get().description)
}

Implementing

Implementing FromForm should be a rare occurence. Prefer instead to use Rocket's built-in derivation.

When implementing FromForm, use use the FormItems iterator to iterate through the raw form key/value pairs. Be aware that form fields that are typically hidden from your application, such as _method, will be present while iterating. Ensure that you adhere to the properties of the strict parameter, as detailed in the documentation below.

Example

Consider the following scenario: we have a struct Item with field name field. We'd like to parse any form that has a field named either balloon or space, and we'd like that field's value to be the value for our structure's field. The following snippet shows how this would be implemented:

use rocket::request::{FromForm, FormItems};

struct Item {
    field: String
}

impl<'f> FromForm<'f> for Item {
    // In practice, we'd use a more descriptive error type.
    type Error = ();

    fn from_form(items: &mut FormItems<'f>, strict: bool) -> Result<Item, ()> {
        let mut field = None;

        for (key, value) in items {
            match key.as_str() {
                "balloon" | "space" if field.is_none() => {
                    let decoded = value.url_decode().map_err(|_| ())?;
                    field = Some(decoded);
                }
                _ if strict => return Err(()),
                _ => { /* allow extra value when not strict */ }
            }
        }

        field.map(|field| Item { field }).ok_or(())
    }
}

Associated Types

The associated error to be returned when parsing fails.

Required Methods

Parses an instance of Self from the iterator of form items it.

Extra form field are allowed when strict is false and disallowed when strict is true.

Errors

If Self cannot be parsed from the given form items, an instance of Self::Error will be returned.

When strict is true and unexpected, extra fields are present in it, an instance of Self::Error will be returned.

Implementors