HTTP

Response classes

class django_htmx.http.HttpResponseClientRedirect(redirect_to: str, *args: Any, **kwargs: Any)

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.

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

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: str, *args: Any, source: str | None = None, event: str | None = None, target: str | None = None, swap: Literal['innerHTML', 'outerHTML', 'beforebegin', 'afterbegin', 'beforeend', 'afterend', 'delete', 'none', None] = None, values: dict[str, str] | None = None, headers: dict[str, str] | None = None, **kwargs: Any)

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.

redirect_to should be the URL to redirect to, as per Django’s HttpResponseRedirect.

source, event, target, swap, values, and headers are all optional, with meaning as documented by htmx.

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: Any, **kwargs: Any)

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.

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: _HttpResponse, url: str | Literal[False]) → _HttpResponse

Set the HX-Push-Url header of response and return it. This header makes htmx push the given URL into the browser location history.

url should be the (relative) URL to push, or False to prevent the location history from being updated.

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: _HttpResponse, method: Literal['innerHTML', 'outerHTML', 'beforebegin', 'afterbegin', 'beforeend', 'afterend', 'delete', 'none']) → _HttpResponse

Set the HX-Reswap header of response and return it. This header overrides the swap method that htmx will use.

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: _HttpResponse, target: str) → _HttpResponse

Set the HX-Retarget header of response and return it. This header overrides the element that htmx will swap content into.

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: _HttpResponse, name: str, params: dict[str, Any] | None = None, *, after: Literal['receive', 'settle', 'swap'] = 'receive') → _HttpResponse

Modify one of the HX-Trigger headers of response and return it. These headers make htmx trigger client-side events.

name is the name of the event to trigger.

params specifies optional JSON-compatible parameters for the event. Uses DjangoJSONEncoder for its extended data type support.

after selects which of the HX-Trigger headers to modify:

• "receive", the default, maps to HX-Trigger

• "settle" maps to HX-Trigger-After-Settle

• "swap" maps to HX-Trigger-After-Swap

Calling trigger_client_event multiple times for the same response and after will update the appropriate header, preserving existing event specifications.

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",
    )