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, select=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.
select (str | None) – Select the content that will be swapped from a response.
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.shortcuts import render from django_htmx.http import HTMX_STOP_POLLING def my_pollable_view(request): if event_finished(): return render(request, "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.replace_url(response, url)[source]¶
Set the
HX-Replace-Url
header ofresponse
and return it. This header causes htmx to replace the current URL in the browser location history.- Parameters:
response (_HttpResponse) – The response to modify and return.
url (str | Literal[False]) – The (relative) URL to replace, or
False
to prevent the location history from being updated.
- Return type:
_HttpResponse
For example:
from django_htmx.http import replace_url def dashboard(request): ... response = render(request, "dashboard.html", ...) # Pretend the user was always on the dashboard, rather than wherever # they were on before. return replace_url(response, "/dashboard/")
- 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 (str) – The swap method.
- Return type:
_HttpResponse
For example:
from django.shortcuts import render 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.shortcuts import render 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(request, "widget-table.html", ...) return retarget(response, "#widgets") # Render just inline table row on failure return render(request, "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.shortcuts import render from django_htmx.http import trigger_client_event def end_of_long_process(request): response = render(request, "end-of-long-process.html") return trigger_client_event( response, "showConfetti", {"colours": ["purple", "red", "pink"]}, after="swap", )