django-htmx 1.8.0

Extension Script

django-htmx comes with a small JavaScript extension for htmx’s behaviour. Currently the extension only includes a debug error handler, documented below.

The script is served as a static file called django-htmx.js, but you shouldn’t reference it directly. Instead, use the included template tags, for both Django and Jinja templates.

For Django Templates, load and use the template tag, after your htmx <script> tag:

{% load django_htmx %}
{% django_htmx_script %}

For Jinja Templates, you need to perform two steps. First, load the tag function into the globals of your custom environment:

# myproject/jinja2.py
from jinja2 import Environment
from django_htmx.jinja import django_htmx_script


def environment(**options):
    env = Environment(**options)
    env.globals.update(
        {
            # ...
            "django_htmx_script": django_htmx_script,
        }
    )
    return env

Second, call the function in your template, after your htmx <script> tag:

{{ django_htmx_script() }}

django_htmx.middleware.HtmxMiddleware

This middleware attaches request.htmx, an instance of HtmxDetails.

See it action in the “Middleware Tester” section of the example app.

django_htmx.middleware.HtmxDetails

This class provides shortcuts for reading the htmx-specific request headers.

def my_view(request):
    if request.htmx:
        template_name = "partial.html"
    else:
        template_name = "complete.html"
    return render(template_name, ...)

django_htmx.http.HttpResponseClientRedirect: type[HttpResponse]

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/")
    ...

django_htmx.http.HttpResponseStopPolling: type[HttpResponse]

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

A constant for the HTTP status code 286, for use with e.g. 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)
    ...

django_htmx.http.trigger_client_event(response, name, *, params, after)

Full signature:

def trigger_client_event(
    response: HttpResponse,
    name: str,
    params: dict[str, Any],
    *,
    after: EventAfterType = "receive"
) -> None:
    ...

Modify the HX-Trigger headers of response to trigger client-side events. Takes the name of the event to trigger and any JSON-compatible parameters for it, and stores them in the appropriate header. Uses DjangoJSONEncoder for its extended data type support.

Which of the HX-Trigger headers is modified depends on the value of after:

• "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 add or replace the given event name and preserve others.

For example:

from django_htmx.http import trigger_client_event


def end_of_long_process(request):
    response = render("end-of-long-process.html")
    trigger_client_event(
        response,
        "showConfetti",
        {"colours": ["purple", "red", "pink"]},
        after="swap",
    )
    return response