Web applications sometimes need to show a one-time notification to the user - e.g. an error message after having failed to login.
These notifications are commonly called flash messages.
actix-web-flash-messages provides a framework to work with flash messages in actix-web, closely modeled after Django's message framework.
```rust use actixweb::{Responder, HttpResponse, get,http}; use actixwebflashmessages::{ FlashMessage, IncomingFlashMessages, }; use std::fmt::Write;
/// Attach two flash messages to the outgoing response, /// a redirect.
async fn set() -> impl Responder { FlashMessage::info("Hey there!").send(); FlashMessage::debug("How is it going?").send(); // Redirect to /show HttpResponse::TemporaryRedirect() .insert_header((http::header::LOCATION, "/show")) .finish() }
/// Pick up the flash messages attached to the request, showing /// them to the user via the request body.
async fn show(messages: IncomingFlashMessages) -> impl Responder { let mut body = String::new(); for message in messages.iter() { writeln!(body, "{} - {}", message.content(), message.level()).unwrap(); } HttpResponse::Ok().body(body) } ```
Add actix-web-flash-messages to your dependencies:
```toml [dependencies]
actix-web = "4" actix-web-flash-messages = "0.4" ```
By default, actix-web-flash-messages does not provide any storage backend to receive and send flash messages.
You can enable:
storage::CookieMessageStore], using the cookies feature flag. The cookie store uses a signed cookie to store and retrieve messages;```toml [dependencies]
actix-web-flash-messages = { version = "0.4", features = ["cookies"] } ```
storage::SessionMessageStore], using the sessions feature flag. The session store attaches flash messages to the current session.```toml [dependencies]
actix-web-flash-messages = { version = "0.4", features = ["sessions"] } ```
You can provide a different message store by implementing the [storage::FlashMessageStore] trait.
You can find examples of application using actix-web-flash-messages on GitHub:
[FlashMessage]s are made of a [Level] and a string of content.
The message level can be used for filtering and rendering - for example:
info level or above in a production environment, while retaining debug level messages for local development; You can build a [FlashMessage] via [FlashMessage::new] by specifying its content and [Level].
You can also use the shorter level-based constructors - e.g. [FlashMessage::info].
To start sending and receiving flash messages you need to register [FlashMessagesFramework] as a middleware on your actix_web's App:
```rust use actixwebflashmessages::{FlashMessagesFramework, storage::CookieMessageStore}; use actixweb::{HttpServer, App, web}; use actix_web::cookie::Key;
async fn main() { let signingkey = Key::generate(); // This will usually come from configuration! let messagestore = CookieMessageStore::builder(signingkey).build(); let messageframework = FlashMessagesFramework::builder(message_store).build();
HttpServer::new(move || {
App::new()
.wrap(message_framework.clone())
// [...] your endpoints
})
} ```
You will then be able to:
FlashMessage]s from incoming requests using the [IncomingFlashMessages] extractor;FlashMessage]s alongside the outgoing response using [FlashMessage::send].```rust use actixweb::{Responder, HttpResponse, get}; use actixwebflashmessages::{ FlashMessage, IncomingFlashMessages, };
/// Send a flash messages alongside the outgoing response, a redirect.
async fn set() -> impl Responder { FlashMessage::info("Hey there!").send(); // [...] }
/// Extract the flash message from the incoming request.
async fn show(_messages: IncomingFlashMessages) -> impl Responder { // [...] } ```
There are a few knobs that you can tweak when it comes to [FlashMessagesFramework].
Use [FlashMessagesFramework::builder] to get access to its fluent configuration API, built around [FlashMessagesFrameworkBuilder].
By default, [FlashMessagesFramework] will only dispatch messages at info-level or above, discarding debug-level messages.
You can change this setting using [FlashMessagesFrameworkBuilder::minimum_level].
```rust use actixwebflashmessages::{FlashMessagesFramework, Level, storage::CookieMessageStore}; use actixweb::{HttpServer, App, web};
fn getmessagestore() -> CookieMessageStore { // [...] # CookieMessageStore::builder(actix_web::cookie::Key::generate()).build() }
async fn main() { // Show debug-level messages when developing locally let minimumlevel = match std::env::var("APPENV") { Ok(s) if &s == "local" => Level::Debug, _ => Level::Info, }; let messageframework = FlashMessagesFramework::builder(getmessagestore()) .minimumlevel(minimum_level) .build();
HttpServer::new(move || {
App::new()
.wrap(message_framework.clone())
// [...] Your endpoints
})
} ```
actix-web-flash-messages provides a cookie-based implementation of flash messages, [storage::CookieMessageStore], using a signed cookie to store and retrieve messages.
You can provide a different message store by implementing the [storage::FlashMessageStore] trait.
Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.