pub trait FromForm<'f>: Sized {
type Error;
// Required method
fn from_form(
it: &mut FormItems<'f>,
strict: bool,
) -> Result<Self, Self::Error>;
}Expand description
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. When deriving FromForm, every
field in the structure must implement
FromFormValue. Rocket validates each field in
the structure by calling its FromFormValue implementation. You may wish to
implement FromFormValue for your own types for custom, automatic
validation.
#[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.description)
}§Implementing
Implementing FromForm should be a rare occurrence. Prefer instead to use
Rocket’s built-in derivation.
When implementing FromForm, 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 item in items {
match item.key.as_str() {
"balloon" | "space" if field.is_none() => {
let decoded = item.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(())
}
}Required Associated Types§
Required Methods§
sourcefn from_form(it: &mut FormItems<'f>, strict: bool) -> Result<Self, Self::Error>
fn from_form(it: &mut FormItems<'f>, strict: bool) -> Result<Self, Self::Error>
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.