Struct Context

pub struct Context<'v> { /* private fields */ }

A form context containing received fields, values, and encountered errors.

A value of this type is produced by the Contextual form guard in its context field. Context contains an entry for every form field submitted by the client regardless of whether the field parsed or validated successfully.

Field Values

The original, submitted field value(s) for a value field can be retrieved via Context::field_value() or Context::field_values(). Data fields do not have their values recorded. All submitted field names, including data field names, can be retrieved via Context::fields().

Field Errors

Serialization

When a value of this type is serialized, a struct or map with the following fields is emitted:

field	type	description
errors	map: string to array of Errors	maps a field name to its errors
values	map: string to array of strings	maps a field name to its form values
data_fields	array of strings	field names of all form data fields
form_errors	array of Errors	errors not associated with a field

See Error for Error serialization details.

Implementations

impl<'v> Context<'v>

pub fn fields(&self) -> impl Iterator<Item = &'v Name> + '_

Returns the names of all submitted form fields, both value and data fields.

Example

use rocket::form::{Form, Contextual};

#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
    let field_names = form.context.fields();
}

pub fn field_value<N: AsRef<Name>>(&self, name: N) -> Option<&'v str>

Returns the first value, if any, submitted for the value field named name.

The type of name may be &Name, &str, or &RawStr. Lookup is case-sensitive but key-separator (. or []) insensitive.

Example

use rocket::form::{Form, Contextual};

#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
    let first_value_for_id = form.context.field_value("id");
    let first_value_for_foo_bar = form.context.field_value("foo.bar");
}

pub fn field_values<N>(&self, name: N) -> impl Iterator<Item = &'v str> + '_

where N: AsRef<Name>,

Returns the values, if any, submitted for the value field named name.

The type of name may be &Name, &str, or &RawStr. Lookup is case-sensitive but key-separator (. or []) insensitive.

Example

use rocket::form::{Form, Contextual};

#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
    let values_for_id = form.context.field_values("id");
    let values_for_foo_bar = form.context.field_values("foo.bar");
}

pub fn errors(&self) -> impl Iterator<Item = &Error<'v>>

Returns an iterator over all of the errors in the context, including those not associated with any field.

Example

use rocket::form::{Form, Contextual};

#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
    let errors = form.context.errors();
}

pub fn field_errors<'a, N>( &'a self, name: N, ) -> impl Iterator<Item = &Error<'v>> + '_

where N: AsRef<Name> + 'a,

Returns the errors associated with the field name. This method is roughly equivalent to:

context.errors().filter(|e| e.is_for(name))

That is, it uses Error::is_for() to determine which errors are associated with the field named name. This considers all errors whose associated field name is a prefix of name to be an error for the field named name. In other words, it associates parent field errors with their children: a.b’s errors apply to a.b.c, a.b.d and so on but not a.c.

Lookup is case-sensitive but key-separator (. or []) insensitive.

Example

use rocket::form::{Form, Contextual};

#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
    // Get all errors for field `id`.
    let id = form.context.field_errors("id");

    // Get all errors for `foo.bar` or `foo` if `foo` failed first.
    let foo_bar = form.context.field_errors("foo.bar");
}

pub fn exact_field_errors<'a, N>( &'a self, name: N, ) -> impl Iterator<Item = &Error<'v>> + '_

where N: AsRef<Name> + 'a,

Returns the errors associated exactly with the field name. Prefer Context::field_errors() instead.

This method is roughly equivalent to:

context.errors().filter(|e| e.is_for_exactly(name))

That is, it uses Error::is_for_exactly() to determine which errors are associated with the field named name. This considers only errors whose associated field name is exactly name to be an error for the field named name. This is not what is typically desired as it ignores errors that occur in the parent which will result in missing errors associated with its children. Use Context::field_errors() in almost all cases.

Lookup is case-sensitive but key-separator (. or []) insensitive.

Example

use rocket::form::{Form, Contextual};

#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
    // Get all errors for field `id`.
    let id = form.context.exact_field_errors("id");

    // Get all errors exactly for `foo.bar`. If `foo` failed, we will
    // this will return no errors. Use `Context::field_errors()`.
    let foo_bar = form.context.exact_field_errors("foo.bar");
}

pub fn status(&self) -> Status

Returns the max of the statuses associated with all field errors.

See Error::status() for details on how an error status is computed.

Example

use rocket::http::Status;
use rocket::form::{Form, Contextual};

#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) -> (Status, &'static str) {
    (form.context.status(), "Thanks!")
}

pub fn push_error(&mut self, error: Error<'v>)

Inject a single error error into the context.

Example

use rocket::http::Status;
use rocket::form::{Form, Contextual, Error};

#[post("/submit", data = "<form>")]
fn submit(mut form: Form<Contextual<'_, T>>) {
    let error = Error::validation("a good error message")
        .with_name("field_name")
        .with_value("some field value");

    form.context.push_error(error);
}

pub fn push_errors<E: Into<Errors<'v>>>(&mut self, errors: E)

Inject all of the errors in errors into the context.

Example

use rocket::http::Status;
use rocket::form::{Form, Contextual, Error};

#[post("/submit", data = "<form>")]
fn submit(mut form: Form<Contextual<'_, T>>) {
    let error = Error::validation("a good error message")
        .with_name("field_name")
        .with_value("some field value");

    form.context.push_errors(vec![error]);
}

Trait Implementations

impl<'v> Debug for Context<'v>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'v> Default for Context<'v>

fn default() -> Context<'v>

Returns the “default value” for a type.

impl<'f> From<Errors<'f>> for Context<'f>

fn from(errors: Errors<'f>) -> Self

Converts to this type from the input type.

impl<'v> Serialize for Context<'v>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.