Djxi | HTMX 4 Integration for Django

Stop scrolling for scattered HTMX!

Djxi lets you architect your HTMX widgets in one single Endpoint Battery. It bundles the urls, view logic, and the HTML into a central hub. The feature lives in one place — without scattering your code across urls, views, and templates.

• No more archaeology. No more digging through three files just to tweak a button label.
• Locality of Behaviour Request → Logic → Render stays in one class.
• Scales cleanly. Small partials stay manageable, without turning your project into spaghetti.
• Django Integration. Tags, Filters, Messages, HX-Headers, CBV and more are frictionless integrated.

Documentation

Please see https://djxi.readthedocs.io/en/latest/.

📦 What is this?

Just a prenup between Grandpa Django and his sexy new HTMX fling — 
preventing scatterbrain syndrome and reactive dysfunction.

Django's Request-Render-Response cycle was architected with full page reloads in mind. The separation into views, urls and templates is practical when the response affect the whole of the client's state.

HTMX introduces minute partial updates via server-side rendered html snippets which update the page selectively and asynchronly. Those small page updates have to be orchestrated and maintained, each with its own view, url and template.

Using Django with HTMX usually results in a scattering of a multitude of template snippest, view logics and url endpoints.

Consider a simple CRUD Todo List: that is 4 urls, 4 views and 5 templates, if you do it with HTMX and create a partial for a todo item. This count can easily go up, as soon as the urge to allow in-place smart actions is given in. The number is not the problem it is the scattering of those snippets (url, view, html) over the codebase under vanilla Django best practices.

Therefore the marriage of Django and HTMX can be bad news for Locality of Behaviour and affect maintability of projects the more it make use of HTMX.

Djxi's solution:

Bundle HTMX urls, views and template collection all into one or more DXEndpointBattery. Here the 'todo-list' feature with all it's actions is described in full in one place and obvious at a glace.

from djxi import DXEndpointBattery, dx_action 

INLINE_TEMPLATE = """
<dx-section name="todo-list-container">
    <div id="todo-list-container">
        <h3>Todo List</h3>
        <input type="search" name="search" value="{{search}}"
            hx-get='{% url "todo:list" %}' hx-trigger="input changed delay:400ms" 
            hx-sync="queue last" hx-target="#todo-list-container" hx-swap="outerHTML">
        <dx-include name="todo-list">
    </div>
</dx-section>

<dx-section name="todo-list">
    <ul id="todo-list" style="list-style: none;">
        {% for item in todo_items %}
            <dx-include name="todo-item">
        {% empty %}
            <li>No todos found.</li>
        {% endfor %}
    </ul>
</dx-section>

<dx-include name="todo-item">
    ...
</dx-section>
"""

class SimpleInlineActionRouter(DXEndpointBattery):
    inline_template = INLINE_TEMPLATE

    def get_item(self, id: int): return TodoItem.objects.get(id=id)
    def get_all(self): return TodoItem.objects.all()

    @dx_get("list", name="list")
    def list(self, request):
        item_qs = self.get_all()
        search = request.GET.get("search", "")
        if search:
            item_qs = item_qs.filter(title__icontains=search)
        return self.render_section(
            request, section_name="todo-list-container", context={"todo_items": item_qs, "search": search}
        )
    ...

For a full demonstration see the todo app in the example django project acompanying Djxi.

Djxi is an opinionated and frictionless HTMX drop-in. It can be run in parallel to vanilla Django views and even alongside the way you used to integrate HTMX with Django.

pip install djxi and streamline new and old HTMX functionalities.

Inline Templates?

HTML in a multiline string? Bäh, I loose all the template syntax higllighting and autocorrection!

No problem at all! Just use the template_name with a path to your template instead of the inline_template. With two files you still have a reasonable LoB score.

Django messaging framework

Djxi integrates fully with the django.contrib.messages package. Once set up, you can just use messages.info(request, "Message to the user") in your async views as well.

To set Djxi messaging up, use the {% flash_messages_inclusion %} templatetag where you'd like to see the messages. You can tweak the appearance by overriding the templates in djxi/messages/*

HX-Headers per middleware

Via the djxi.middleware.DjxiHeadersMiddleware the request and response objects have the htmx to read incoming Request Headers and set outgoing Response Header to adjust HTMX on the client.

Pre-Alpha Note The package is considered in pre-alpha state, use with as an experimental package.

• Happy to hear from you if you like to contribute to the project.
• Watch out for updates and consider giving it a star.
• Checkout the djxi showcases in the example django app.

Getting Started

Instalation

1. Install with pip:

python -m pip install djxi

2. Add django-htmx to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    "djxi",
    ...,
]

3. Optional: Adjust your base template to get you up and running instantly

 {% load djxi %}
 <!doctype html>
 <html>
   <head>
     ...
     {% htmx_script_inclusion %}
   </head>
   <body {% htmx_headers %}>
     ...
   </body>
 </html>

The htmx_script_inclusion tag will pull the unminified v4 from CDN. Set DX_HTMX_VERSION="2" to pull in v2. For prodution you likely want to serve your own minified htmx.js.

As there are significant syntax changes between v4 and v2 of htmx, keep DX_HTMX_VERSION in sync with what htmx version you are using.

Configuration

In your settings file you can overide the following default values for Djxi:

• DX_HTMX_VERSION: "4" # allow ['2', '4']
• DX_HTMX_COMPRESSION: ".js" # allow: ['.js','.min.js']
• DX_SECTION_TAG: "dx-section" # html tag to delineate html snippets

FAQ

• Why HTMX 4 Djxi defaults to HTMX 4 as it is the up and comming iteration on version 2, with many changes and improvement. While it works with HTMX 2 as well, in the future Djxi may drop support for HTMX 2.