Django HTMX Showcase

A comprehensive demonstration of HTMX integration with Django, showcasing various interactive web techniques without writing JavaScript.

Overview

This project demonstrates how to use HTMX with Django to create modern, interactive web applications with minimal JavaScript. HTMX allows you to access AJAX, CSS Transitions, WebSockets, and Server Sent Events directly in HTML, using attributes, so you can build dynamic interfaces with the simplicity of Django's template system.

Features

The showcase includes the following examples:

1. Click to Load

Load additional content when a button is clicked without refreshing the page.

2. Form Submission

Submit forms and update the DOM with server responses, all without page refreshes.

3. Infinite Scroll

Automatically load more content when the user scrolls to the bottom of the page.

4. Active Search

Filter and search through content as you type, with real-time results.

5. Table Sort

Sort table data by clicking on column headers, with backend processing.

6. Modal Dialog

Open modal dialogs with content loaded from the server.

Technologies Used

• Django 5.0.6 - Python web framework
• HTMX 2.0.4 - Modern browser features, directly in HTML
• Bulma CSS - CSS framework for styling
• Docker - Containerization
• uv - Fast Python package installer and resolver
• Faker - Generating test data

Installation

Prerequisites

• Docker and Docker Compose
• Git

Setup

1. Clone the repository:

   git clone https://github.com/Krytos/Django-HTMX-Docker-Template.git
   cd Django-HTMX-Docker-Template

2. Start the Docker containers:

   docker compose up app

3. The application will be available at http://localhost:8000

Development

Running Tests

docker compose --profile test watch

Project Structure

django-htmx-showcase/
├── app/
│   ├── htmx_project/          # Django project settings
│   ├── showcase/              # Main application with HTMX examples
│   │   ├── migrations/        # Database migrations
│   │   ├── templates/         # HTML templates (examples organized here)
│   │   │   ├── base.html      # Base template with common elements
│   │   │   ├── index.html     # Home page with links to all examples
│   │   │   ├── partials/      # Partial templates for HTMX responses
│   │   ├── admin.py           # Django admin configuration
│   │   ├── forms.py           # Forms for the application
│   │   ├── models.py          # Data models
│   │   ├── urls.py            # URL routing
│   │   └── views.py           # View functions for all examples
│   ├── manage.py              # Django management script
│   ├── populate_contacts.py   # Script to generate sample data
│   ├── Dockerfile             # Docker configuration for the app
│   └── pyproject.toml         # Python dependencies and project config
└── compose.yaml               # Docker Compose configuration

Key Concepts

How HTMX Works with Django

HTMX allows you to make AJAX requests directly from HTML attributes. When combined with Django's template system, this enables dynamic web applications with minimal JavaScript:

1. HTML elements use attributes like hx-get, hx-post, hx-trigger, etc.
2. HTMX intercepts these events and makes requests to your Django endpoints
3. Django views return HTML fragments (usually from partial templates)
4. HTMX updates the DOM with the returned HTML

Example Pattern

A typical HTMX + Django pattern:

1. In your template:

   <button hx-get="{% url 'load_more' %}" 
           hx-target="#content" 
           hx-swap="appendChild">
     Load More
   </button>
   <div id="content">
     <!-- Content goes here -->
   </div>

2. In your urls.py:

   path('load-more/', views.load_more, name='load_more')

3. In your views.py:

   def load_more(request):
       # Get some data
       return render(request, 'partials/more_content.html', {'data': data})

4. In your partial template (partials/more_content.html):

   <div class="item">{{ data }}</div>

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• HTMX - For making interactive web interfaces simpler
• Django - For the amazing web framework
• Bulma - For the CSS framework