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

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.


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)]

extern crate rocket;

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 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.


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.


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.

Implementations on Foreign Types

impl<'f> FromForm<'f> for &'f str

This implementation should only be used during debugging!

impl<'f, T: FromForm<'f>> FromForm<'f> for Option<T>

impl<'f, T: FromForm<'f>> FromForm<'f> for Result<T, T::Error>