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 subclass of HttpResponseRedirect 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 of response 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 of response 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 of response 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 of response 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 of response and return it. These headers make htmx trigger client-side events.

Calling trigger_client_event multiple times for the same response and after 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 to HX-Trigger
- "settle" maps to HX-Trigger-After-Settle
- "swap" maps to HX-Trigger-After-Swap
encoder (type[JSONEncoder]) –
The JSONEncoder class used to generate the JSON. Defaults to DjangoJSONEncoder 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",
    )