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::param::{FromParam, FromSegments};
|
||||
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 http::hyper::{FreshHyperResponse, StatusCode};
|
||||
|
||||
/// A failing response; simply forwards to the catcher for the given
|
||||
/// `StatusCode`.
|
||||
#[derive(Debug)]
|
||||
pub struct Failure(pub StatusCode);
|
||||
|
||||
|
|
|
@ -7,6 +7,35 @@ use http::hyper::{HyperSetCookie, HyperCookiePair, FreshHyperResponse};
|
|||
|
||||
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> {
|
||||
name: String,
|
||||
message: String,
|
||||
|
@ -14,6 +43,19 @@ pub struct 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> {
|
||||
Flash {
|
||||
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> {
|
||||
Flash::new(responder, "warning", msg)
|
||||
}
|
||||
|
||||
/// Constructs a "success" `Flash` message with the given `responder` and
|
||||
/// `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> {
|
||||
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> {
|
||||
Flash::new(responder, "error", msg)
|
||||
}
|
||||
|
@ -60,17 +141,18 @@ impl Flash<()> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Returns the `name` of this message.
|
||||
pub fn name(&self) -> &str {
|
||||
self.name.as_str()
|
||||
}
|
||||
|
||||
/// Returns the `msg` contents of this message.
|
||||
pub fn msg(&self) -> &str {
|
||||
self.message.as_str()
|
||||
}
|
||||
}
|
||||
|
||||
// TODO: Using Flash<()> is ugly. Either create a type FlashMessage = Flash<()>
|
||||
// or create a Flash under request that does this.
|
||||
// This is Type-Aliased in Request.
|
||||
impl<'r> FromRequest<'r> for Flash<()> {
|
||||
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 redirect;
|
||||
mod with_status;
|
||||
|
|
Loading…
Reference in New Issue