mirror of https://github.com/rwf2/Rocket.git
Document the Failure and Flash responses.
This commit is contained in:
parent
d24d5534f4
commit
c2d3bdccdb
|
@ -9,3 +9,6 @@ pub use self::request::Request;
|
||||||
pub use self::from_request::{FromRequest, Outcome};
|
pub use self::from_request::{FromRequest, Outcome};
|
||||||
pub use self::param::{FromParam, FromSegments};
|
pub use self::param::{FromParam, FromSegments};
|
||||||
pub use self::form::{Form, FromForm, FromFormValue, FormItems};
|
pub use self::form::{Form, FromForm, FromFormValue, FormItems};
|
||||||
|
|
||||||
|
/// Type alias to retrieve flash messages from a request.
|
||||||
|
pub type FlashMessage = ::response::Flash<()>;
|
||||||
|
|
|
@ -2,6 +2,8 @@ use outcome::Outcome;
|
||||||
use response::{self, Responder};
|
use response::{self, Responder};
|
||||||
use http::hyper::{FreshHyperResponse, StatusCode};
|
use http::hyper::{FreshHyperResponse, StatusCode};
|
||||||
|
|
||||||
|
/// A failing response; simply forwards to the catcher for the given
|
||||||
|
/// `StatusCode`.
|
||||||
#[derive(Debug)]
|
#[derive(Debug)]
|
||||||
pub struct Failure(pub StatusCode);
|
pub struct Failure(pub StatusCode);
|
||||||
|
|
||||||
|
|
|
@ -7,6 +7,35 @@ use http::hyper::{HyperSetCookie, HyperCookiePair, FreshHyperResponse};
|
||||||
|
|
||||||
const FLASH_COOKIE_NAME: &'static str = "_flash";
|
const FLASH_COOKIE_NAME: &'static str = "_flash";
|
||||||
|
|
||||||
|
/// Sets a "flash" cookies that will be removed the next time it is accessed.
|
||||||
|
/// The anologous type on the request side is
|
||||||
|
/// [FlashMessage](/rocket/request/type.FlashMessage.html).
|
||||||
|
///
|
||||||
|
/// This type makes it easy to send messages across requests. It is typically
|
||||||
|
/// used for "status" messages after redirects. For instance, if a user attempts
|
||||||
|
/// to visit a page he/she does not have access to, you may want to redirect the
|
||||||
|
/// user to a safe place and show a message indicating what happened on the
|
||||||
|
/// redirected page. The message should only persist for a single request. This
|
||||||
|
/// can be accomplished with this type.
|
||||||
|
///
|
||||||
|
/// # Usage
|
||||||
|
///
|
||||||
|
/// Each `Flash` message consists of a `name` and some `msg` contents. A generic
|
||||||
|
/// constructor ([new](#method.new)) can be used to construct a message with any
|
||||||
|
/// name, while the [warning](#method.warning), [success](#method.success), and
|
||||||
|
/// [error](#method.error) constructors create messages with the corresponding
|
||||||
|
/// names.
|
||||||
|
///
|
||||||
|
/// Messages can be retrieved on the request side via the
|
||||||
|
/// [FlashMessage](/rocket/request/type.FlashMessage.html) type and the
|
||||||
|
/// [name](#method.name) and [msg](#method.msg) methods.
|
||||||
|
///
|
||||||
|
/// # Responder
|
||||||
|
///
|
||||||
|
/// The `Responder` implementation for `Flash` sets the message cookie and then
|
||||||
|
/// uses the passed in responder `res` to complete the response. In other words,
|
||||||
|
/// it simply sets a cookie and delagates the rest of the response handling to
|
||||||
|
/// the wrapped responder.
|
||||||
pub struct Flash<R> {
|
pub struct Flash<R> {
|
||||||
name: String,
|
name: String,
|
||||||
message: String,
|
message: String,
|
||||||
|
@ -14,6 +43,19 @@ pub struct Flash<R> {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl<R: Responder> Flash<R> {
|
impl<R: Responder> Flash<R> {
|
||||||
|
/// Constructs a new `Flash` message with the given `name`, `msg`, and
|
||||||
|
/// underlying `responder`.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// Construct a "suggestion" message with contents "Try this out!" that
|
||||||
|
/// redirects to "/".
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// use rocket::response::{Redirect, Flash};
|
||||||
|
///
|
||||||
|
/// let msg = Flash::new(Redirect::to("/"), "suggestion", "Try this out!");
|
||||||
|
/// ```
|
||||||
pub fn new<N: AsRef<str>, M: AsRef<str>>(res: R, name: N, msg: M) -> Flash<R> {
|
pub fn new<N: AsRef<str>, M: AsRef<str>>(res: R, name: N, msg: M) -> Flash<R> {
|
||||||
Flash {
|
Flash {
|
||||||
name: name.as_ref().to_string(),
|
name: name.as_ref().to_string(),
|
||||||
|
@ -22,14 +64,53 @@ impl<R: Responder> Flash<R> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
pub fn warning<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
|
/// Constructs a "success" `Flash` message with the given `responder` and
|
||||||
Flash::new(responder, "warning", msg)
|
/// `msg`.
|
||||||
}
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// Construct a "success" message with contents "It worked!" that redirects
|
||||||
|
/// to "/".
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// use rocket::response::{Redirect, Flash};
|
||||||
|
///
|
||||||
|
/// let msg = Flash::success(Redirect::to("/"), "It worked!");
|
||||||
|
/// ```
|
||||||
pub fn success<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
|
pub fn success<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
|
||||||
Flash::new(responder, "success", msg)
|
Flash::new(responder, "success", msg)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Constructs a "warning" `Flash` message with the given `responder` and
|
||||||
|
/// `msg`.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// Construct a "warning" message with contents "Watch out!" that redirects
|
||||||
|
/// to "/".
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// use rocket::response::{Redirect, Flash};
|
||||||
|
///
|
||||||
|
/// let msg = Flash::warning(Redirect::to("/"), "Watch out!");
|
||||||
|
/// ```
|
||||||
|
pub fn warning<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
|
||||||
|
Flash::new(responder, "warning", msg)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Constructs an "error" `Flash` message with the given `responder` and
|
||||||
|
/// `msg`.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// Construct an "error" message with contents "Whoops!" that redirects
|
||||||
|
/// to "/".
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// use rocket::response::{Redirect, Flash};
|
||||||
|
///
|
||||||
|
/// let msg = Flash::error(Redirect::to("/"), "Whoops!");
|
||||||
|
/// ```
|
||||||
pub fn error<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
|
pub fn error<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
|
||||||
Flash::new(responder, "error", msg)
|
Flash::new(responder, "error", msg)
|
||||||
}
|
}
|
||||||
|
@ -60,17 +141,18 @@ impl Flash<()> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Returns the `name` of this message.
|
||||||
pub fn name(&self) -> &str {
|
pub fn name(&self) -> &str {
|
||||||
self.name.as_str()
|
self.name.as_str()
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Returns the `msg` contents of this message.
|
||||||
pub fn msg(&self) -> &str {
|
pub fn msg(&self) -> &str {
|
||||||
self.message.as_str()
|
self.message.as_str()
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
// TODO: Using Flash<()> is ugly. Either create a type FlashMessage = Flash<()>
|
// This is Type-Aliased in Request.
|
||||||
// or create a Flash under request that does this.
|
|
||||||
impl<'r> FromRequest<'r> for Flash<()> {
|
impl<'r> FromRequest<'r> for Flash<()> {
|
||||||
type Error = ();
|
type Error = ();
|
||||||
|
|
||||||
|
|
|
@ -1,3 +1,9 @@
|
||||||
|
//! Types and traits to build and send responses.
|
||||||
|
//!
|
||||||
|
//! The return type of a Rocket handler can be any type that implements the
|
||||||
|
//! [Responder](trait.Responder.html) trait. This module contains several useful
|
||||||
|
//! types that implement this trait.
|
||||||
|
|
||||||
mod responder;
|
mod responder;
|
||||||
mod redirect;
|
mod redirect;
|
||||||
mod with_status;
|
mod with_status;
|
||||||
|
|
Loading…
Reference in New Issue