Skip to content

spookylukey/django-htmx-patterns

Repository files navigation

Django + htmx patterns

This repo is a rough-and-ready compilation of the patterns I’m using and developing when writing Django projects that use htmx, with complete example code.

The docs are intended to be viewed on GitHub: https://github.com/spookylukey/django-htmx-patterns/ and the code can be run locally if needed.

My aims are to document and share:

  1. The basic patterns and control flow needed
  2. Some enhancements we can make with a few utilities

The code presented depends only on Django and htmx, unless otherwise noted. I won’t be packaging it up as a library. It is instead being released into the public domain, and you are encouraged to copy-paste it for your own needs. (See the “Approach” docs for why).

There are some Django packages that provide shortcuts for some of the things mentioned here, such as django-htmx, but I won’t be using any of them for the sake of clarity.

Contents

This is a work in progress, I’ll try to keep it up to date. PRs welcome.

tl;dr

The biggest contributions in this repo are:

  • inline partials with block selection in the template.

    This is a pattern which allows you to keep the parts of the page together for great “locality of behaviour”, and avoid the view code having to know anything about which template fragments/partials are being used. Template code changes for htmx are usually a matter of wrapping some parts of a template in a Django template block and adding standard htmx attributes. View code changes for htmx are often just adding a single decorator on the view function: @for_htmx(use_block_from_params=True).

    This pattern makes a huge difference to htmx usability in Django.

  • full example of field-by-field htmx form validation, while keeping Django’s Form abstraction and all its benefits.

  • nice patterns for doing modals

Requirements

Monsters

My example code includes sad and happy monsters that can be hugged or kicked to change their state. Please note that I do not endorse the kicking of monsters, nor advise hugging them.

Code folder

In the code folder is a demo app which has full working examples of everything in the docs.

To install locally, create and activate a virtualenv, and then do:

cd code
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

Feedback

Your feedback is very welcome! Star this repo if you like it, and please share ideas on discussions.

Links

Some other good htmx resources:

If you liked this repo, you might also be helped by some of my other resources: