Django + htmx patterns

This repo is a rough-and-ready compilation of the patterns I’m using and
developing when writing Django <https://www.djangoproject.com/>_ projects that
use htmx <https://htmx.org/>_, 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:

The basic patterns and control flow needed
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 <https://github.com/adamchainz/django-htmx>_, but I won’t be using any of them
for the sake of clarity.

Approach <./approach.rst>_
Base template <./base_template.rst>_
Headers <./headers.rst>_
Post requests <./posts.rst>_
Partials using separate templates <./separate_partials.rst>_
Separate partials with a single view <./separate_partials_single_view.rst>_
Inline partials <./inline_partials.rst>_
Single view with actions combined <./actions.rst>_
View restart <./view_restart.rst>_
django-functest patterns <./django_functest.rst>_
Modal dialogs <./modals.rst>_
Form validation <./form_validation.rst>_

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 <https://github.com/spookylukey/django-htmx-patterns/blob/master/inline_partials.rst#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 <./form_validation.rst>_, while keeping Django’s Form abstraction and all its benefits.
nice patterns for doing modals <./modals.rst>_

Requirements

Django <https://www.djangoproject.com/>_
htmx <https://htmx.org/>_ (see Base template <./base_template.rst>_ for suggested installation docs)
The nicest patterns here require django-render-block <https://github.com/clokep/django-render-block>_::

pip install django-render-block

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 <./code/>_ 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 <https://github.com/spookylukey/django-htmx-patterns/discussions>_.