Crates.io | axum-htmx |
lib.rs | axum-htmx |
version | 0.6.0 |
source | src |
created_at | 2023-07-22 23:37:06.348086 |
updated_at | 2024-06-24 22:16:29.83431 |
description | A set of htmx extractors, responders, and request guards for axum. |
homepage | |
repository | https://github.com/robertwayne/axum-htmx |
max_upload_size | |
id | 923469 |
size | 113,123 |
axum-htmx
is a small extension library providing extractors, responders, and
request guards for htmx headers within
axum.
Run cargo add axum-htmx
to add the library to your project.
All of the htmx request headers
have a supported extractor. Extractors are infallible, meaning they will always
succeed and never return an error. In the case where a header is not present,
the extractor will return None
or false
dependant on the expected return
type.
Header | Extractor | Value |
---|---|---|
HX-Boosted |
HxBoosted |
bool |
HX-Current-URL |
HxCurrentUrl |
Option<axum::http::Uri> |
HX-History-Restore-Request |
HxHistoryRestoreRequest |
bool |
HX-Prompt |
HxPrompt |
Option<String> |
HX-Request |
HxRequest |
bool |
HX-Target |
HxTarget |
Option<String> |
HX-Trigger-Name |
HxTriggerName |
Option<String> |
HX-Trigger |
HxTrigger |
Option<String> |
All of the htmx response headers
have a supported responder. A responder is a basic type that implements
IntoResponseParts
, allowing you to simply and safely apply the HX-* headers to
any of your responses.
Header | Responder | Value |
---|---|---|
HX-Location |
HxLocation |
axum::http::Uri |
HX-Push-Url |
HxPushUrl |
axum::http::Uri |
HX-Redirect |
HxRedirect |
axum::http::Uri |
HX-Refresh |
HxRefresh |
bool |
HX-Replace-Url |
HxReplaceUrl |
axum::http::Uri |
HX-Reswap |
HxReswap |
axum_htmx::responders::SwapOption |
HX-Retarget |
HxRetarget |
String |
HX-Reselect |
HxReselect |
String |
HX-Trigger |
HxResponseTrigger |
axum_htmx::serde::HxEvent |
HX-Trigger-After-Settle |
HxResponseTrigger |
axum_htmx::serde::HxEvent |
HX-Trigger-After-Swap |
HxResponseTrigger |
axum_htmx::serde::HxEvent |
Also, there are corresponding cache-related headers, which you may want to add to
GET
responses, depending on the htmx headers.
For example, if your server renders the full HTML when the HX-Request
header is
missing or false
, and it renders a fragment of that HTML when HX-Request: true
,
you need to add Vary: HX-Request
. That causes the cache to be keyed based on a
composite of the response URL and the HX-Request
request header - rather than
being based just on the response URL.
Refer to caching htmx docs section for details.
Header | Responder |
---|---|
Vary: HX-Request |
VaryHxRequest |
Vary: HX-Target |
VaryHxTarget |
Vary: HX-Trigger |
VaryHxTrigger |
Vary: HX-Trigger-Name |
VaryHxTriggerName |
Look at the Auto Caching Management section for
automatic Vary
headers management.
Requires feature auto-vary
.
Manual use of Vary Reponders adds fragility to the code, because of the need to manually control correspondence between used extractors and the responders.
We provide a middleware to address this issue by
automatically adding Vary
headers when corresponding extractors are used.
For example, on extracting [HxRequest
], the middleware automatically adds
Vary: hx-request
header to the response.
Look at the usage example.
Requires feature guards
.
In addition to the extractors, there is also a route-wide layer request guard
for the HX-Request
header. This will redirect any requests without the header
to "/" by default.
It should be noted that this is NOT a replacement for an auth guard. A user can
trivially set the HX-Request
header themselves. This is merely a convenience
for preventing users from receiving partial responses without context. If you
need to secure an endpoint you should be using a proper auth system.
In this example, we'll look for the HX-Boosted
header, which is set when
applying the hx-boost attribute to an
element. In our case, we'll use it to determine what kind of response we send.
When is this useful? When using a templating engine, like
minijinja, it is common to extend
different templates from a _base.html
template. However, htmx works by sending
partial responses, so extending our _base.html
would result in lots of extra
data being sent over the wire.
If we wanted to swap between pages, we would need to support both full template
responses and partial responses (as the page can be accessed directly or
through a boosted anchor), so we look for the HX-Boosted
header and extend
from a _partial.html
template instead.
use axum::response::IntoResponse;
use axum_htmx::HxBoosted;
async fn get_index(HxBoosted(boosted): HxBoosted) -> impl IntoResponse {
if boosted {
// Send a template extending from _partial.html
} else {
// Send a template extending from _base.html
}
}
We can trigger any event being listened to by the DOM using an htmx trigger header.
use axum_htmx::HxResponseTrigger;
// When we load our page, we will trigger any event listeners for "my-event.
async fn index() -> (HxResponseTrigger, &'static str) {
// Note: As HxResponseTrigger only implements `IntoResponseParts`, we must
// return our trigger first here.
(
HxResponseTrigger::normal(["my-event", "second-event"]),
"Hello, world!",
)
}
htmx
also allows arbitrary data to be sent along with the event, which we can
use via the serde
feature flag and the HxEvent
type.
use serde_json::json;
// Note that we are using `HxResponseTrigger` from the `axum_htmx::serde` module
// instead of the root module.
use axum_htmx::{HxEvent, HxResponseTrigger};
async fn index() -> (HxResponseTrigger, &'static str) {
let event = HxEvent::new_with_data(
"my-event",
// May be any object that implements `serde::Serialize`
json!({"level": "info", "message": {
"title": "Hello, world!",
"body": "This is a test message.",
}}),
)
.unwrap();
// Note: As HxResponseTrigger only implements `IntoResponseParts`, we must
// return our trigger first here.
(HxResponseTrigger::normal([event]), "Hello, world!")
}
use axum::Router;
use axum_htmx::HxRequestGuardLayer;
fn router_one() -> Router {
Router::new()
// Redirects to "/" if the HX-Request header is not present
.layer(HxRequestGuardLayer::default())
}
fn router_two() -> Router {
Router::new()
.layer(HxRequestGuardLayer::new("/redirect-to-this-route"))
}
Flag | Default | Description | Dependencies |
---|---|---|---|
auto-vary |
Disabled | A middleware to address htmx caching issue | futures , tokio , tower |
guards |
Disabled | Adds request guard layers. | tower , futures-core , pin-project-lite |
serde |
Disabled | Adds serde support for the HxEvent and LocationOptions |
serde , serde_json |
Contributions are always welcome! If you have an idea for a feature or find a bug, let me know. PR's are appreciated, but if it's not a small change, please open an issue first so we're all on the same page!
cargo +nightly test --all-features
axum-htmx
is dual-licensed under either
at your option.