Document the Failure and Flash responses.

This commit is contained in:
Sergio Benitez 2016-11-02 18:48:43 +01:00
parent d24d5534f4
commit c2d3bdccdb
4 changed files with 99 additions and 6 deletions

View File

@ -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<()>;

View File

@ -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);

View File

@ -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 = ();

View File

@ -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;