Struct rocket::form::Context[][src]

pub struct Context<'v> { /* fields omitted */ }
Expand description

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:

fieldtypedescription
errorsmap: string to array of Errorsmaps a field name to its errors
valuesmap: string to array of stringsmaps a field name to its form values
data_fieldsarray of stringsfield names of all form data fields
form_errorsarray of Errorserrors not associated with a field

See Error for Error serialization details.

Implementations

impl<'v> Context<'v>[src]

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

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>[src]

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>, 
[src]

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>>[src]

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, 
[src]

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, 
[src]

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 chilren. 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 erorrs. Use `Context::field_errors()`.
    let foo_bar = form.context.exact_field_errors("foo.bar");
}

pub fn status(&self) -> Status[src]

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

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

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>[src]

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

Formats the value using the given formatter. Read more

impl<'v> Default for Context<'v>[src]

fn default() -> Context<'v>[src]

Returns the “default value” for a type. Read more

impl<'f> From<Errors<'f>> for Context<'f>[src]

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

Performs the conversion.

impl<'v> Serialize for Context<'v>[src]

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer
[src]

Serialize this value into the given Serde serializer. Read more

Auto Trait Implementations

impl<'v> !RefUnwindSafe for Context<'v>

impl<'v> Send for Context<'v>

impl<'v> !Sync for Context<'v>

impl<'v> Unpin for Context<'v>

impl<'v> !UnwindSafe for Context<'v>

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

pub fn type_id(&self) -> TypeId[src]

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

pub fn borrow(&self) -> &T[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

pub fn borrow_mut(&mut self) -> &mut T[src]

Mutably borrows from an owned value. Read more

impl<T> From<T> for T[src]

pub fn from(t: T) -> T[src]

Performs the conversion.

impl<T> Instrument for T[src]

fn instrument(self, span: Span) -> Instrumented<Self>[src]

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self>[src]

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

pub fn into(self) -> U[src]

Performs the conversion.

impl<T> IntoCollection<T> for T

pub fn into_collection<A>(self) -> SmallVec<A> where
    A: Array<Item = T>, 

Converts self into a collection.

pub fn mapped<U, F, A>(self, f: F) -> SmallVec<A> where
    F: FnMut(T) -> U,
    A: Array<Item = U>, 

impl<T> Same<T> for T

type Output = T

Should always be Self

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]

Performs the conversion.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>[src]

Performs the conversion.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>, 

pub fn vzip(self) -> V