What is HTMX?
HTMX is a powerful tool that allows developers to create highly interactive and dynamic user interfaces without the need for heavy JavaScript frameworks. At its core, HTMX uses HTML attributes to define behaviour, making it an ideal companion to traditional server-side frameworks such as Django.
Key features of HTMX:
Simplicity: HTMX simplifies the process of adding dynamic functionality to web applications by using familiar HTML attributes such as hx-get, hx-post, and hx-trigger.
Minimal JavaScript: Unlike complex JavaScript frameworks, HTMX requires minimal JavaScript code, reducing the overhead associated with client-side scripting.
Server-side rendering: HTMX integrates seamlessly with server-side rendering frameworks such as Django, allowing developers to leverage the power of both front-end and back-end technologies.
Progressive enhancement: HTMX follows the principle of progressive enhancement, ensuring that basic functionality is available to all users, while improving the experience for those with JavaScript-enabled browsers.
Compatibility: HTMX is compatible with all modern browsers and works well with existing web technologies, making it easy to integrate into existing projects.
How HTMX works with Django:
In a Django application, HTMX can be used to create dynamic UI elements within Django templates, enabling real-time updates without reloading pages. By using Django's powerful template language alongside HTMX attributes, developers can easily create dynamic and responsive web applications.
Benefits of using HTMX with Django include
Simplified development: HTMX simplifies the development process by allowing developers to focus on writing HTML and Python code rather than complex JavaScript logic.
Improved performance: With its minimal JavaScript footprint, HTMX helps improve the performance of Django applications by reducing the amount of client-side processing required.
Improved user experience: By enabling real-time updates and interactions, HTMX improves the overall user experience, resulting in higher user engagement and satisfaction.
In the next section, we'll dive into the process of setting up a Django project with HTMX, using Poetry for dependency management.
Setting up the Project
No interest in reading step by step guide, here is the full example in Github.
Poetry is a dependency management tool for Python that simplifies the process of managing project dependencies and virtual environments. In this section, we'll guide you through setting up a new Django project with Poetry and installing the necessary dependencies for integrating HTMX.
1. Install Poetry: First, make sure you have Poetry installed on your system. You can install Poetry using the following command:
curl -sSL https://install.python-poetry.org | python3 -
For alternative installation methods, refer to the Poetry documentation.
2. Create a New Folder: Create a new folder for your Django project. You can do this using your system's file explorer or the command line:
mkdir my_django_project
cd my_django_project
3. Initialize Poetry: Initiate a new Poetry project within your project folder by running the following command:
poetry init
Follow the interactive prompt to provide details about your project, such as its name, version, and dependencies.
4. Install Dependencies: Once the Poetry project is initialized, you can start installing the required dependencies. Run the following command to install the core dependencies:
poetry add django django-htmx django-crispy-forms crispy-bootstrap5 django-render-block
This command will add Django, django-htmx, django-crispy-forms, crispy-bootstrap5, and django-render-block to your project's dependencies.
5. Add Development Dependencies: Additionally, you may want to add development dependencies for tasks such as code formatting, linting, and debugging. You can install these dependencies using the following command:
poetry add black ruff djlint ipdb ipython --group dev
This command will add black, ruff, djlint, ipdb, and ipython as development dependencies.
Setting up the Django Project
Now that we have installed the necessary dependencies with Poetry, let's proceed to set up the Django project. In this section, we'll guide you through initializing a new Django project and configuring it to integrate with HTMX.
1. Initialize Django Project: Run the following command to initialize a new Django project in the current directory:
django-admin startproject django_htmx .
This command creates a new Django project named django_htmx in the current directory. The dot (.) at the end specifies that the project should be created in the current directory.
2. Configure Settings: Navigate to the django_htmx directory and open the settings.py file within your favorite text editor. Update the INSTALLED_APPS setting to include the installed dependencies:
INSTALLED_APPS = [
...
'django_htmx',
'crispy_forms',
'crispy_bootstrap5',
'django_render_block',
'htmx',
]
Make sure to replace 'app_name' with the name of your Django app.
3. Configure Middleware: In the same settings.py file, add the HTMX middleware to the MIDDLEWARE setting:
MIDDLEWARE = [
...
'htmx.middleware.HtmxMiddleware',
]
This middleware is essential for HTMX to intercept and process AJAX requests.
Django-htmx adds extra parameters to the request based on the recognised headers, making it easy for us to use them later in our views. E.g. the request.htmx which we can use to know if the request is coming from htmx or not.
4. Configure Crispy Forms: If you plan to use Crispy Forms for styling your forms, add the following settings to settings.py:
CRISPY_ALLOWED_TEMPLATE_PACKS = 'bootstrap5'
CRISPY_TEMPLATE_PACK = 'bootstrap5'
This configures Crispy Forms to use Bootstrap 5 for styling.
5. Run Migrations: Before you can start using your Django project, you need to apply the initial database migrations. Run the following command:
python manage.py migrate
This command creates the necessary database tables for your Django project.
6. Verify Setup: To verify that the project setup is successful, you can start the Django development server by running:
python manage.py runserver
Open a web browser and navigate to http://127.0.0.1:8000. If you see the Django welcome page, congratulations! Your Django project is set up and ready to integrate with HTMX.
Great! Let's set up the todos app with the provided model, URLs, and admin configurations.
Todos app
1. Create thetodosApp: If you haven't already created the todos app, you can create it using the following command:
python manage.py startapp todos
This command will create a new app named todos.
2. Define the Model: Inside the models.py file of the todos app, define the TodoItem model as provided:
# todos/models.py
from django.db import models
class TodoItem(models.Model):
title = models.CharField(max_length=100)
completed_on = models.DateTimeField(null=True, blank=True)
class Meta:
ordering = ["-id"]
def __str__(self):
return self.title
3. Define the URLs: Create a urls.py file inside the todos app directory and define the URLs as provided:
# todos/urls.py
from django.urls import path
from . import views
app_name = "todos"
urlpatterns = [
path("", views.TodoItemListView.as_view(), name="todoitem-list"),
path("create/", views.TodoItemCreateView.as_view(), name="todoitem-create"),
path("<int:pk>/mark-complete/", views.TodoMarkComplete.as_view(), name="todoitem-mark-complete"),
path("<int:pk>/delete/", views.TodoItemDeleteView.as_view(), name="todoitem-delete"),
]
4. Create Views (to be implemented): You'll need to create the views mentioned in the URLs (views.py) for TodoItemListView, TodoItemCreateView, TodoMarkComplete, and TodoItemDeleteView.
5. Register Model with Admin: In the admin.py file of the todos app, register the TodoItem model as provided:
# todos/admin.py
from django.contrib import admin
from .models import TodoItem
@admin.register(TodoItem)
class TodoItemAdmin(admin.ModelAdmin):
list_display = ("title", "completed_on")
search_fields = ("title",)
6. Configure Settings: Make sure the todos app is included in the INSTALLED_APPS list in your project's settings.py file.
Integrating HTMX with Class-Based Views in Django
In this section, we'll explore how to integrate HTMX with Django's Class-Based Views (CBVs) using a custom HtmxTemplateResponseMixin. We'll examine the provided views.py file, which contains CBVs for handling todo items in our Django application, and explain how each view contributes to creating dynamic user interfaces with HTMX.
# todos/views.py
# Import necessary modules and classes
from typing import Any
from django import forms
from django.http import HttpResponse
from django.shortcuts import redirect
from django.template.response import TemplateResponse
from django.urls import reverse_lazy
from django.utils import timezone
from django.views.generic import CreateView, DeleteView, ListView, View
from django_htmx.http import retarget
from render_block import render_block_to_string
from todos.forms import TodoItemForm
from todos.models import TodoItem
# Define a custom TemplateResponse class for HTMX integration
class HtmxResponseClass(TemplateResponse):
def __init__(self, htmx_template_block: str | None = None, *args, **kwargs):
self.htmx_template_block = htmx_template_block
super().__init__(*args, **kwargs)
@property
def rendered_content(self):
context = self.resolve_context(self.context_data)
if self._request.htmx and self.htmx_template_block:
return render_block_to_string(
self.template_name,
block_name=self.htmx_template_block,
context=self.context_data,
request=self._request,
)
template = self.resolve_template(self.template_name)
return template.render(context, self._request)
# Define a mixin for HTMX template responses
class HtmxTemplateResponseMixin:
response_class = HtmxResponseClass
htmx_template_block = None
def render_to_response(self, context, **response_kwargs):
response_kwargs.setdefault("content_type", self.content_type)
return self.response_class(
request=self.request,
template=self.get_template_names(),
context=context,
using=self.template_engine,
htmx_template_block=self.htmx_template_block,
**response_kwargs,
)
# Define a view for listing todo items
class TodoItemListView(HtmxTemplateResponseMixin, ListView):
model = TodoItem
template_name = "todos/todoitem_list.html"
context_object_name = "todoitems"
ordering = ["-id"]
htmx_template_block = "object_list_block"
def get_context_data(self, **kwargs: Any) -> dict[str, Any]:
context = super().get_context_data(**kwargs)
context["form"] = TodoItemForm()
return context
# Define a view for creating todo items
class TodoItemCreateView(HtmxTemplateResponseMixin, CreateView):
form_class = TodoItemForm
template_name = "todos/todoitem_list.html"
htmx_template_block = "form_block"
http_method_names = ["post"]
success_url = reverse_lazy("todos:todoitem-list")
def form_invalid(self, form: forms.ModelForm) -> HttpResponse:
response = super().form_invalid(form)
return retarget(response, "this")
# Define a view for deleting todo items
class TodoItemDeleteView(DeleteView):
model = TodoItem
success_url = reverse_lazy("todos:todoitem-list")
http_method_names = ["post"]
# Define a view for marking todo items as complete
class TodoMarkComplete(View):
http_method_names = ["post"]
def post(self, request, *args, **kwargs):
todoitem = TodoItem.objects.get(pk=kwargs["pk"])
todoitem.completed_on = timezone.now()
todoitem.save()
return redirect("todos:todoitem-list")
Understanding the Views
Now, let's break down what each view does:
TodoItemListView: This view lists all todo items in the database. It utilizes the
HtmxTemplateResponseMixinto handle HTMX requests, so that we return the whole content when accessing the page via the browser and only the list when accessing it via HTMX requests.The
get_context_datamethod adds a form (TodoItemForm) to the context to enable the creation of new todo items.TodoItemCreateView: This view handles the creation of new todo items. It uses the
HtmxTemplateResponseMixinto handle HTMX requests and overrides theform_invalidmethod to return an HTMX response with validation errors.TodoItemDeleteView: This view deletes todo items from the database. It specifies the model (
TodoItem) and the success URL to redirect to after deletion.TodoMarkComplete: This view marks a todo item as complete by updating its
completed_onfield with the current timestamp. It redirects the user to the todo item list view (TodoItemListView) after marking the item as complete.
By using CBVs with the HtmxTemplateResponseMixin, we can seamlessly integrate HTMX functionality into our Django application, providing users with a dynamic and interactive user experience.
Django Templates
In this section, we'll define a base HTML template (base.html) that serves as the foundation for our HTMX-powered Django application. This template provides the necessary structure and includes links to Bootstrap for styling and HTMX for seamless AJAX interactions.
1. Add Template Directory to Settings: Before creating the base template, ensure that the templates directory is configured in your Django project's settings.py file:
# settings.py
TEMPLATES = [
{
...
'DIRS': [BASE_DIR / "templates"],
...
},
]
This configuration specifies the location of the templates directory relative to the project's base directory.
2. Define Base Template (base.html):
<!-- templates/base.html -->
{% load static %}
{% load django_htmx %}
<!DOCTYPE html>
<html lang="en" data-bs-theme="dark">
<head>
<meta name="description"
content="HTMXANGO is a Django application that demonstrates how to use HTMX with Django.">
<meta name="keywords" content="HTMXANGO, HTMX, Django, Python">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
{% block title %}
HTMXANGO
{% endblock title %}
</title>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css"
rel="stylesheet"
integrity="sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN"
crossorigin="anonymous">
<link rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.0/font/bootstrap-icons.css">
{% block styles %}
{% endblock styles %}
</head>
<body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}'>
<div class="container">
{% block content %}
{% endblock content %}
</div>
{% block scripts %}
{% endblock scripts %}
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js"
integrity="sha384-C6RzsynM9kWDrMNeT87bh95OGNyZPhcTNXj1NW7RuBCsyN/o0jlpcV8Qyq46cDfL"
crossorigin="anonymous"></script>
<script src="https://unpkg.com/htmx.org@1.9.10" defer></script>
{% django_htmx_script %}
</body>
</html>
Understanding the Base Template:
Load Static Files: The
{% load static %}tag allows us to reference static files such as CSS and JavaScript within our templates.Load Django-HTMX Tags: The
{% load django_htmx %}tag enables the usage of HTMX-specific template tags and attributes.HTML Structure: The template follows standard HTML5 structure with
<head>and<body>sections.Title Block: The
{% block title %}tag allows child templates to define their own titles while providing a default title ("HTMX Django").Bootstrap Integration: The template includes links to Bootstrap CSS and JavaScript files for styling and interactivity.
CSRF Token: The
hx-headersattribute ensures that HTMX requests include the CSRF token for security purposes.Content Block: The
{% block content %}tag defines a placeholder for child templates to inject their content.Scripts Block: The
{% block scripts %}tag defines a placeholder for additional JavaScript scripts.HTMX Integration: The template includes HTMX JavaScript library (
htmx.min.js) and the{% django_htmx_script %}tag for HTMX-specific configurations django-htmx third party app.Understanding the Use of CSRF Token in HTMX Requests
In the base HTML template (
base.html) provided for our HTMX-powered Django application, you may have noticed the inclusion of thehx-headersattribute with the CSRF token in the<body>tag:<body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}'>This addition serves a crucial security purpose when making HTMX requests within our application.
Why include a CSRF token in HTMX requests?
Django protects against Cross-Site Request Forgery (CSRF) attacks by requiring the inclusion of a CSRF token in requests that change state (e.g. POST requests). This token is typically included in forms as a hidden field and is validated by Django to ensure that the request comes from the same site and is not forged by a malicious third party.
If we are using HTMX to make AJAX requests within our application, we need to ensure that these requests include the CSRF token so that Django can validate them properly. Including the CSRF token in HTMX requests helps prevent CSRF attacks and ensures the security of our application.
How it works
By including the
hx-headersattribute with the CSRF token in the tag, we instruct HTMX to include this token in all AJAX requests made within our application. This ensures that each request contains the necessary CSRF token for Django to validate.
Implementing Todo List Template with HTMX
In this section, we'll define the todoitem_list.html template, which is responsible for displaying the list of todo items in our HTMX-powered Django application. This template extends the base template (base.html) and includes HTMX-specific attributes and functionality for dynamic interactions.
1. Define Todo List Template (todoitem_list.html):
<!-- templates/todos/todoitem_list.html -->
{% extends "base.html" %}
{% load crispy_forms_tags %}
{% block content %}
<div class="row align-items-center">
<div class="row">
<h1>Todo Item</h1>
<div class="spinner-border htmx-indicator" role="status" id="spinner">
<span class="sr-only">Loading...</span>
</div>
{% block form_block %}
<form method="post"
hx-post="{% url 'todos:todoitem-create' %}"
hx-swap="innerHTML"
hx-trigger="submit"
hx-target="#todo-list"
hx-indicator="#spinner">
{% crispy form %}
<button type="submit" class="btn btn-primary">Save</button>
</form>
{% endblock form_block %}
</div>
<div class="row">
<h1>Todo List</h1>
<div id="todo-list">
{% block object_list_block %}
{% if todoitems %}
<table class="table table-striped">
<thead>
<tr>
<th scope="col" class="col-1">#</th>
<th scope="col" class="col-5">Title</th>
<th scope="col" class="col-6">Completed</th>
</tr>
</thead>
<tbody>
{% for todo in todoitems %}
<tr>
<th scope="row">{{ todo.id }}</th>
<td>{{ todo.title }}</td>
<td>
<input class="form-check-input"
type="checkbox"
value=""
id="completed-checkbox"
{% if todo.completed_on %}checked{% endif %}
hx-post="{% url 'todos:todoitem-mark-complete' todo.id %}"
hx-swap="outerHTML"
hx-target="closest table"
hx-trigger="click"
{% if todo.completed_on %}disabled{% endif %}>
<label class="form-check-label" for="completed-checkbox">
{% if todo.completed_on %}
{{ todo.completed_on }}
{% else %}
Not Completed
{% endif %}
</label>
<button hx-post="{% url 'todos:todoitem-delete' todo.id %}"
hx-confirm="Are you sure?"
hx-swap="outerHTML"
hx-target="closest table"
hx-trigger="click"
class="btn btn-danger btn-sm float-end"
tooltip="Delete Todo Item">
<i class="bi bi-trash"></i>
</button>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p>No todo items found.</p>
{% endif %}
{% endblock object_list_block %}
</div>
</div>
</div>
{% endblock content %}
Understanding the Todo List Template:
Extending Base Template: The template extends the
base.htmltemplate to inherit its structure and functionality.Load Crispy Forms Tags: The
{% load crispy_forms_tags %}tag enables the usage of Crispy Forms for rendering forms in a Bootstrap-friendly manner.Content Block: The
{% block content %}tag defines the main content area of the template.Todo Item Form: The form block includes a form for creating new todo items. The form is submitted via HTMX with AJAX, and the response replaces the content of the todo list (
#todo-list).Todo List Display: The
object_list_blockblock iterates over todo items and displays them in a table format. Each todo item includes options to mark as complete or delete using HTMX-powered interactions.HTMX Attributes: HTMX attributes (
hx-post,hx-swap,hx-target,hx-trigger,hx-indicator,hx-confirm) are used to define AJAX behavior, such as posting data, swapping HTML content, and indicating loading state.
In this section, we've defined the todoitem_list.html template to display the list of todo items in our HTMX-powered Django application. This template uses HTMX attributes and functionality to enable dynamic interactions such as creating, marking as complete, and deleting todo items, all without refreshing the page.
Testing HTMX Views in Django
We'll write the test cases test_views.py to ensure the functionality of our HTMX-powered views in the Django application. These test cases cover various scenarios, including rendering templates, handling form submissions, and processing AJAX requests.
1. Define Test Cases (test_views.py):
# todos/tests/test_views.py
from django.test import TestCase
from django.urls import reverse
from todos.forms import TodoItemForm
from todos.models import TodoItem
class TodoItemListViewTests(TestCase):
# Test case to check rendering of the todo item list view
def test_get(self):
response = self.client.get(reverse("todos:todoitem-list"))
self.assertEqual(response.status_code, 200)
self.assertIn("form", response.context_data)
self.assertIsInstance(response.context_data["form"], TodoItemForm)
# Test case to check rendering of the todo item list view with HTMX
def test_get_with_htmx(self):
response = self.client.get(
reverse("todos:todoitem-list"), headers={"hx-request": "true"}
)
self.assertEqual(response.status_code, 200)
self.assertContains(response, "No todo items found.")
self.assertNotContains(response, "form")
# Additional test cases for other views (TodoItemCreateView, TodoItemDeleteView, TodoMarkCompleteTests) are omitted for brevity.
Understanding the Test Cases:
TestCase Class Structure: Each test case class inherits from
django.test.TestCase, providing access to Django's testing utilities.TodoItemListViewTests: This class contains test cases for the todo item list view (
TodoItemListView).test_get: Tests the rendering of the todo item list view and ensures that the form is present in the context.test_get_with_htmx: Tests the rendering of the todo item list view with HTMX enabled and verifies that the form is not included in the response.
Additional Test Cases: Similar test cases are defined for other views (
TodoItemCreateView,TodoItemDeleteView,TodoMarkCompleteTests) to cover their respective functionalities. (check the github link at the end for the full example)
Conclusion
In this article, we've looked at integrating HTMX with Django to create dynamic and interactive web applications. HTMX provides a lightweight and intuitive way to add AJAX functionality to Django projects, enabling seamless user experiences without the need for complex JavaScript frameworks.
We started by setting up a Django project with the necessary dependencies and configuring the HTMX middleware. We then defined models, views, templates and tests for a todo application, showing how HTMX simplifies the implementation of dynamic features such as form submissions, real-time updates and interactive user interfaces.
Through examples such as the todo item list view and form submissions, we demonstrated the power and flexibility of HTMX in extending Django applications. With HTMX, developers can leverage the simplicity of Django's templates and views while adding rich client-side interactions.
Testing HTMX views ensures the reliability and correctness of our application, allowing us to deploy features into production with confidence. By writing comprehensive test cases, we can verify that our HTMX-powered views behave as expected under various conditions.
To further explore and experiment with the codebase discussed in this article, you can access the full example on GitHub. Feel free to fork, clone, and contribute to the project, and unlock the full potential of HTMX in your Django applications.
With HTMX, developers can deliver modern, responsive, and user-friendly web applications while leveraging the simplicity and robustness of the Django framework. Whether you're building a todo app, a dashboard, or an e-commerce platform, HTMX enables you to create delightful experiences for your users.
Harness the power of HTMX and take your Django projects to new heights of interactivity and engagement. Happy coding!