How To Set Messages

hx-requests leverages Django’s messaging framework to deliver asynchronous messages. This is a convenient way to notify users when a form is valid or invalid, or to display any other message without requiring a full page reload.

Add Settings to settings.py

Set HX_REQUESTS_USE_HX_MESSAGES: to True (default is False)

Define HX_REQUESTS_HX_MESSAGES_TEMPLATE in settings to the path of the messages template. The context in the template has access to messages.

HX_REQUESTS_USE_HX_MESSAGES = True # Default is False
HX_REQUESTS_HX_MESSAGES_TEMPLATE = "path/to/your/messages_template.html"

messages_template.html

<div id="hx_messages" hx-swap-oob='true'>
    <ul class="messages">
        {% for message in messages %}
            <li class="alert {{ message.tags }}">{{ message|safe }}</li>
        {% endfor %}
    </ul>
</div>

Notes:

This follows the same structure as Django’s Messages

Tip

The same template can be used for Django’s messages framework and for hx-requests (hx-swap-oob is required)

Add A Div to the Base Template

This is where the messages will be rendered. Htmx’s hx-swap-oob is leveraged to swap in the messages. This ensures that messages can be swapped in with other Html snippets.

<div id="hx_messages" hx-swap-oob='true'></div>

Setting a Message

You can set a message anywhere within an HxRequest the same way you would set a message in Django.

from django.contrib import messages

def form_valid(self, **kwargs) -> str:
    self.form.save()

    # Set a message
    messages.success(self.request, "Form saved successfully")

    return ...

def form_invalid(self, **kwargs) -> str:
    # Set a message
    messages.error(self.request, "Form is invalid")

    return ...

Disabling Messages

If HX_REQUESTS_USE_HX_MESSAGES is set to True, there are some default messages set in some of the HxRequests. To disable messages on any HxRequest set show_messages to False

class MyHxRequest(BaseHxRequest):
    ...
    show_messages = False

Tip

Tip

Toasts are an effective template for asynchronous messages because the page doesn’t reload. While a user might miss a message banner displayed at the top of the page, a toast fixed to the top-right corner will always be visible.