HTTP tools#
Response classes#
- class django_htmx.http.HttpResponseClientRedirect(redirect_to, *args, **kwargs)[source]#
htmx can trigger a client side redirect when it receives a response with the
HX-Redirect
header.HttpResponseClientRedirect
is a HttpResponseRedirect subclass for triggering such redirects.- Parameters:
redirect_to (str) – The path to redirect to, as per
HttpResponseRedirect
.args (Any) – Other
HTTPResponse
parameters.kwargs (Any) – Other
HTTPResponse
parameters.
For example:
from django_htmx.http import HttpResponseClientRedirect def sensitive_view(request): if not sudo_mode.active(request): return HttpResponseClientRedirect("/activate-sudo-mode/") ...
- class django_htmx.http.HttpResponseClientRefresh[source]#
htmx will trigger a page reload when it receives a response with the
HX-Refresh
header.HttpResponseClientRefresh
is a custom response class that allows you to send such a response. It takes no arguments, since htmx ignores any content.For example:
from django_htmx.http import HttpResponseClientRefresh def partial_table_view(request): if page_outdated(request): return HttpResponseClientRefresh() ...
- class django_htmx.http.HttpResponseLocation(redirect_to, *args, source=None, event=None, target=None, swap=None, values=None, headers=None, **kwargs)[source]#
An HTTP response class for sending the
HX-Location
header. This header makes htmx make a client-side “boosted” request, acting like a client side redirect with a page reload.- Parameters:
redirect_to (str) –
The path to redirect to, as per
HttpResponseRedirect
.source (str | None) – The source element of the request.
event (str | None) – The event that “triggered” the request.
target (str | None) – CSS selector to target.
swap (Literal['innerHTML', 'outerHTML', 'beforebegin', 'afterbegin', 'beforeend', 'afterend', 'delete', 'none', None]) – How the response will be swapped into the target.
values (dict[str, str] | None) – values to submit with the request.
headers (dict[str, str] | None) – headers to submit with the request.
args (Any) – Other
HTTPResponse
parameters.kwargs (Any) – Other
HTTPResponse
parameters.
For example:
from django_htmx.http import HttpResponseLocation def wait_for_completion(request, action_id): ... if action.completed: return HttpResponseLocation(f"/action/{action.id}/completed/") ...
- class django_htmx.http.HttpResponseStopPolling(*args, **kwargs)[source]#
When using a polling trigger, htmx will stop polling when it encounters a response with the special HTTP status code 286.
HttpResponseStopPolling
is a custom response class with that status code.- Parameters:
args (Any) – Other
HTTPResponse
parameters.kwargs (Any) – Other
HTTPResponse
parameters.
For example:
from django_htmx.http import HttpResponseStopPolling def my_pollable_view(request): if event_finished(): return HttpResponseStopPolling() ...
- django_htmx.http.HTMX_STOP_POLLING: int = 286#
A constant for the HTTP status code 286. You can use this instead of
HttpResponseStopPolling
to stop htmx from polling.For example, with Django’s render shortcut:
from django_htmx.http import HTMX_STOP_POLLING def my_pollable_view(request): if event_finished(): return render("event-finished.html", status=HTMX_STOP_POLLING) ...
Response modifying functions#
- django_htmx.http.push_url(response, url)[source]#
Set the
HX-Push-Url
header ofresponse
and return it. This header makes htmx push the given URL into the browser location history.- Parameters:
response (_HttpResponse) – The response to modify and return.
url (str | Literal[False]) – The (relative) URL to push, or
False
to prevent the location history from being updated.
- Return type:
_HttpResponse
For example:
from django_htmx.http import push_url def leaf(request, leaf_id): ... if leaf is None: # Directly render branch view response = branch(request, branch=leaf.branch) return push_url(response, f"/branch/{leaf.branch.id}") ...
- django_htmx.http.reswap(response, method)[source]#
Set the
HX-Reswap
header ofresponse
and return it. This header overrides the swap method that htmx will use.- Parameters:
response (_HttpResponse) – The response to modify and return.
method (Literal['innerHTML', 'outerHTML', 'beforebegin', 'afterbegin', 'beforeend', 'afterend', 'delete', 'none']) – The swap method.
- Return type:
_HttpResponse
For example:
from django_htmx.http import reswap def employee_table_row(request): ... response = render(...) if employee.is_boss: reswap(response, "afterbegin") return response
- django_htmx.http.retarget(response, target)[source]#
Set the
HX-Retarget
header ofresponse
and return it. This header overrides the element that htmx will swap content into.- Parameters:
response (_HttpResponse) – The response to modify and return.
target (str) – CSS selector to target.
- Return type:
_HttpResponse
For example:
from django.views.decorators.http import require_POST from django_htmx.http import retarget @require_POST def add_widget(request): ... if form.is_valid(): # Rerender the whole table on success response = render("widget-table.html", ...) return retarget(response, "#widgets") # Render just inline table row on failure return render("widget-table-row.html", ...)
- django_htmx.http.trigger_client_event(response, name, params=None, *, after='receive', encoder=<class 'django.core.serializers.json.DjangoJSONEncoder'>)[source]#
Modify one of the
HX-Trigger
headers ofresponse
and return it. These headers make htmx trigger client-side events.Calling
trigger_client_event
multiple times for the sameresponse
andafter
will update the appropriate header, preserving existing event specifications.- Parameters:
response (_HttpResponse) – The response to modify and return.
name (str) – The name of the event to trigger.
params (dict[str, Any] | None) – Optional JSON-compatible parameters for the event.
after (Literal['receive', 'settle', 'swap']) –
Which
HX-Trigger
header to modify:"receive"
, the default, maps toHX-Trigger
"settle"
maps toHX-Trigger-After-Settle
"swap"
maps toHX-Trigger-After-Swap
encoder (type[JSONEncoder]) –
The
JSONEncoder
class used to generate the JSON. Defaults toDjangoJSONEncoder
for its extended data type support.
- Return type:
_HttpResponse
For example:
from django_htmx.http import trigger_client_event def end_of_long_process(request): response = render("end-of-long-process.html") return trigger_client_event( response, "showConfetti", {"colours": ["purple", "red", "pink"]}, after="swap", )