django-htmx-views 0.1.0__py3-none-any.whl

django_htmx_views-0.1.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: django-htmx-views
+Version: 0.1.0
+Summary: Reusable Django view services for HTMX-enabled applications
+Author: Gavin Burnell
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gb119/django-htmx-views
+Project-URL: Repository, https://github.com/gb119/django-htmx-views
+Project-URL: Issues, https://github.com/gb119/django-htmx-views/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: django-htmx>=1.17
+Provides-Extra: docs
+Requires-Dist: Sphinx<9,>=7; extra == "docs"
+Requires-Dist: django-ajax-selects>=2.2; extra == "docs"
+Requires-Dist: sphinx-better-theme>=0.1.5; extra == "docs"
+Provides-Extra: linked-selects
+Requires-Dist: django-ajax-selects>=2.2; extra == "linked-selects"
+Provides-Extra: test
+Requires-Dist: build>=1.2; extra == "test"
+Requires-Dist: django-ajax-selects>=2.2; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-django>=4.8; extra == "test"
+Requires-Dist: tomli>=2; python_version < "3.11" and extra == "test"
+Requires-Dist: twine>=5; extra == "test"
+Dynamic: license-file
+
+# django-htmx-views
+
+Reusable Django view mixins and widgets for building HTMX-enabled applications.
+This package extracts the `htmx_views` app used by
+[`gb119/labman`](https://github.com/gb119/labman) and
+[`uolphysicsteaching/phas_vitals`](https://github.com/uolphysicsteaching/phas_vitals)
+so that the implementation can be installed and maintained independently.
+
+The initial package source is an exact copy of the newer `phas_vitals`
+implementation at commit
+[`1008bc4`](https://github.com/uolphysicsteaching/phas_vitals/commit/1008bc475a28a0ccca40df8769ad6902b68edebc).
+The two upstream apps were compared before extraction and are not currently
+identical; see [UPSTREAM_COMPARISON.md](UPSTREAM_COMPARISON.md) for the
+verification details.
+
+## Features
+
+- HTMX-aware dispatch for Django class-based views.
+- Routing by HTMX trigger name, trigger ID, or target ID.
+- HTMX-specific templates, context data, and context object names.
+- HTMX-aware form-valid and form-invalid handlers.
+- Optional linked `<select>` widgets backed by `django-ajax-selects`.
+
+## Installation
+
+Install the core package:
+
+```console
+python -m pip install django-htmx-views
+```
+
+Install linked-select support as well:
+
+```console
+python -m pip install "django-htmx-views[linked-selects]"
+```
+
+Add the app and `django-htmx` middleware to the host project's settings:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "htmx_views",
+]
+
+MIDDLEWARE = [
+    # ...
+    "django_htmx.middleware.HtmxMiddleware",
+]
+```
+
+## HTMX-aware views
+
+Importing `htmx_views.views` installs the existing HTMX-aware dispatch hook on
+Django's base `View` class. Mix `HTMXProcessMixin` into a class-based view to
+route HTMX requests to element-specific handlers:
+
+```python
+from django.http import HttpResponse
+from django.views.generic import TemplateView
+
+from htmx_views.views import HTMXProcessMixin
+
+
+class ResultsView(HTMXProcessMixin, TemplateView):
+    template_name = "results/page.html"
+    template_name_results = "results/_table.html"
+
+    def htmx_get_refresh(self, request, *args, **kwargs):
+        return HttpResponse("refreshed")
+```
+
+For an HTMX `GET`, the mixin looks for handlers using the request's
+`trigger_name`, `trigger`, and `target`, in that order. Element names are
+lowercased and stripped of characters other than letters, numbers, and
+underscores. The same convention is available for `DELETE`, `PATCH`, `POST`,
+and `PUT`.
+
+`HTMXFormMixin` adds equivalent `htmx_form_valid_<element>` and
+`htmx_form_invalid_<element>` hooks for form views.
+
+## Linked selects
+
+Linked selects are optional because they require `django-ajax-selects`. After
+installing the `linked-selects` extra, include the package URLs:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path(
+        "htmx-views/",
+        include(("htmx_views.urls", "htmx_views"), namespace="htmx_views"),
+    ),
+]
+```
+
+Then use a registered `django-ajax-selects` lookup:
+
+```python
+from django import forms
+
+from htmx_views.widgets import HTMXSelectWidget
+
+
+class EquipmentForm(forms.Form):
+    module = forms.ModelChoiceField(queryset=...)
+    category = forms.ModelChoiceField(
+        queryset=...,
+        widget=HTMXSelectWidget("categories", parent="module"),
+    )
+```
+
+The linked-select endpoint runs the lookup's authorisation check before
+querying it. Importing linked-select modules without the optional dependency
+raises an actionable `ImportError`; the core view mixins remain usable.
+
+## Migrating an existing project
+
+1. Install this package and add `"htmx_views"` to `INSTALLED_APPS`.
+2. Replace imports beginning with `apps.htmx_views` with `htmx_views`.
+3. If linked selects are used, install the extra and include
+   `htmx_views.urls` under the `htmx_views` namespace.
+4. Remove the project's copied `apps/htmx_views` directory after its tests
+   pass against the package.
+
+The former `htmx_views.views.LinkedSelectEndpointView` import remains available
+for compatibility.
+
+## Development and builds
+
+Create a development environment and run the tests:
+
+```console
+python -m pip install -e ".[test,linked-selects]"
+python -m pytest
+```
+
+Build and validate the wheel and source distribution:
+
+```console
+python -m build
+python -m twine check dist/*
+```
+
+Build the noarch Conda package with `conda-build`:
+
+```console
+conda-build conda-recipe
+```
+
+The GitHub Actions build workflow runs the tests and produces both Python and
+Conda package artifacts.
+
+## Documentation
+
+The full documentation is published at
+[gb119.github.io/django-htmx-views](https://gb119.github.io/django-htmx-views/).
+
+Build it locally with:
+
+```console
+python -m pip install -e ".[docs]"
+python -m sphinx -W --keep-going -b html docs/source docs/build/html
+```
+
+The documentation workflow rebuilds and deploys GitHub Pages for published
+releases and pre-releases, and can also be started manually.
+
+## Publishing a release
+
+Creating a GitHub release, including a pre-release, runs the release workflow.
+It verifies that the release tag (for example, `vX.Y.Z`) matches
+`htmx_views.__version__`, reruns the tests, builds both package formats, and
+publishes:
+
+- the wheel and source distribution to PyPI;
+- the noarch Conda package to the `phygbu` Anaconda channel with the `main`
+  label.
+
+Configure these GitHub Actions repository secrets before publishing:
+
+- `PYPI_TOKEN`: a PyPI API token authorised for `django-htmx-views`;
+- `ANACONDA`: an Anaconda.org API token authorised to upload to `phygbu`.
+
+The upload steps deliberately refuse to overwrite an existing Conda package.
+
+## License
+
+MIT

django_htmx_views-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+django_htmx_views-0.1.0.dist-info/licenses/LICENSE,sha256=-kGm_gyRmInhSKjaHveNSHKvwZ8ccUzUsUo_UueFPdk,1070
+htmx_views/__init__.py,sha256=x75QnkCan48wE0DIdfiFDroLIw2hlcfGmUhG746bDBE,92
+htmx_views/_optional.py,sha256=OYas-2IakdQ5GapcTQebhEenyYri1-787Yi3K5Qurmc,655
+htmx_views/apps.py,sha256=Q9t6QQ1u9x_jmY4JRFx1yiNildRvMRZ9oXNA9Nou_5Q,436
+htmx_views/linked_selects.py,sha256=K-ZzxJU8JUcZAEliRrK_chdPHvcebmAqnenKlVrRztc,1847
+htmx_views/models.py,sha256=gGlplAaqxiVGsJvXnSdoGaOkvM9-T5EipGjKB11agPE,85
+htmx_views/urls.py,sha256=TMLEVMj6g_nFttXWzJChQ_0e581b7X66p_a7utnfYRY,374
+htmx_views/views.py,sha256=FRCSZrsYwJDfJD_hL2vyAj9YKauLVInZ16xCYk3gQLA,14234
+htmx_views/widgets.py,sha256=OXa3H0AWVlgROVTVyS3SfihUGGJXNYWXxLIMfRW9fac,2359
+htmx_views/templates/htmx_views/widgets/options.html,sha256=roJAarRWuoyzK4numxGJaTc28h8TEvi3dywAN_-fEPo,136
+htmx_views/templates/htmx_views/widgets/select.html,sha256=ueVtSskiarnW3PfHc9O0q_PgNBqn41H5LHeOY2JCJfk,141
+htmx_views/templatetags/__init__.py,sha256=B5LHgOXUzESA8__ksIlw5JWb5GjQPL_TpAPXAgDAYyE,44
+django_htmx_views-0.1.0.dist-info/METADATA,sha256=BCStN2V1g45bMWV1oA4J1UHxXMg_T8sW092fl9Bas_Q,7415
+django_htmx_views-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+django_htmx_views-0.1.0.dist-info/top_level.txt,sha256=9dOhcM3sntUymDFIPzE0_eSuTSkRmltIxZBxUL1fzGE,11
+django_htmx_views-0.1.0.dist-info/RECORD,,

django_htmx_views-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_htmx_views-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gavin Burnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_htmx_views-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+htmx_views

htmx_views/__init__.py

@@ -0,0 +1,3 @@
+"""HTMX views package for handling HTMX-specific view components."""
+
+__version__ = "0.1.0"

htmx_views/_optional.py

@@ -0,0 +1,19 @@
+"""Helpers for optional HTMX views integrations."""
+
+# Python imports
+from importlib import import_module
+
+
+def get_ajax_select_registry():
+    """Return the ajax-select registry or explain how to enable linked selects."""
+    try:
+        ajax_select = import_module("ajax_select")
+    except ModuleNotFoundError as error:
+        if error.name != "ajax_select":
+            raise
+        raise ImportError(
+            "Linked-select support requires the optional dependency "
+            "'django-ajax-selects'. Install it before importing "
+            "'htmx_views.widgets' or 'htmx_views.urls'."
+        ) from error
+    return ajax_select.registry

htmx_views/apps.py

@@ -0,0 +1,20 @@
+from __future__ import unicode_literals
+
+# Python imports
+from os.path import basename, dirname
+
+# Django imports
+from django.apps import AppConfig
+
+
+class HTMXViewsConfig(AppConfig):
+    """Django App config object for the htmx_views app."""
+
+    name = basename(dirname(__file__))
+    default = True
+
+
+class EquipmentConfig(HTMXViewsConfig):
+    """Compatibility name for code importing the former app config."""
+
+    default = False

htmx_views/linked_selects.py

@@ -0,0 +1,50 @@
+"""Linked-select endpoint backed by the optional django-ajax-selects package."""
+
+# Django imports
+from django.core.exceptions import ImproperlyConfigured
+from django.http import Http404
+from django.views.generic import TemplateView
+
+# app imports
+from ._optional import get_ajax_select_registry
+
+registry = get_ajax_select_registry()
+
+
+class LinkedSelectEndpointView(TemplateView):
+    """Return linked-select options from an authorised lookup."""
+
+    http_method_names = ["get", "head", "options"]
+    template_name = "htmx_views/widgets/options.html"
+
+    def dispatch(self, request, *args, **kwargs):
+        """Resolve the lookup and enforce its authorisation policy."""
+        self.lookup_channel = kwargs.get("lookup_channel")
+        try:
+            self.lookup = registry.get(self.lookup_channel)
+        except ImproperlyConfigured as error:
+            raise Http404("Unknown linked-select lookup channel.") from error
+
+        self.lookup.check_auth(request)
+        self.parent = request.GET.get("_htmx_parent") or getattr(self.lookup, "parameter_name", None)
+        return super().dispatch(request, *args, **kwargs)
+
+    def get_context_data(self, **kwargs):
+        """Add the option list to the context."""
+        if self.parent is None:
+            raise ImproperlyConfigured(
+                f"Creating an htmx_views widget for {self.lookup_channel} without knowing the trigger."
+            )
+        query = self.request.GET.get(self.parent)
+        try:
+            query = int(query)
+        except (TypeError, ValueError):
+            pass
+
+        context = super().get_context_data(**kwargs)
+        context["options"] = []
+        if query:
+            context["options"] = [
+                (item.pk, str(item)) for item in self.lookup.get_query(query, self.request).distinct()
+            ]
+        return context

htmx_views/models.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""
+Created on Thu Dec 26 14:46:18 2024
+
+@author: phygbu
+"""

htmx_views/templates/htmx_views/widgets/options.html

@@ -0,0 +1,4 @@
+<option value="">---------</option>
+{% for value, label in options %}
+    <option value="{{ value }}">{{ label }}</option>
+{% endfor %}

htmx_views/templates/htmx_views/widgets/select.html

@@ -0,0 +1,3 @@
+<select name="{{ widget.name }}"{% include "django/forms/widgets/attrs.html" %} id="id_{{ name }}">
+    <option>Select...</option>
+</select>

htmx_views/templatetags/__init__.py

@@ -0,0 +1 @@
+"""Template tags package for HTMX views."""

htmx_views/urls.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+"""urls for the hhtmx_views app."""
+# Python imports
+from os.path import basename, dirname
+
+# Django imports
+from django.urls import path
+
+# app imports
+from .linked_selects import LinkedSelectEndpointView
+
+app_name = basename(dirname(__file__))
+urlpatterns = [path("select/<str:lookup_channel>/", LinkedSelectEndpointView.as_view(), name="select")]

htmx_views/views.py

@@ -0,0 +1,335 @@
+# -*- coding: utf-8 -*-
+"""View support classes and functions for htmx-views."""
+
+# Python imports
+import logging
+import re
+from contextlib import contextmanager
+
+# Django imports
+from django.conf import settings
+from django.views import View
+
+logger = logging.getLogger(__name__)
+
+
+@contextmanager
+def temp_attr(obj, attr, value):
+    """Temporarily set the value of an attribute and restore it afterwards."""
+    # Check if the attribute originally exists on the object
+    has_attr = hasattr(obj, attr)
+    original_value = getattr(obj, attr, None)
+
+    # Set the attribute to the new value
+    setattr(obj, attr, value)
+
+    try:
+        # Yield control back to the caller
+        yield
+    finally:
+        if has_attr:
+            # Restore the original value if the attribute existed
+            setattr(obj, attr, original_value)
+        else:
+            # Delete the attribute if it didn't exist originally
+            delattr(obj, attr)
+
+
+def dispatch(self, request, *args, **kwargs):
+    """Dispatch method that becomes htmx aware.
+
+    If the =`htmx` request attribute is set (by django-htmx) and the method name is in either
+    `self.http_method_names` or `self.htmx_method_names` then try to locate the method
+    `htmx_<http_verb>` method and call that or else fall back to the regular `<http_verb>` method.
+
+    If an approrpiate method can't be located, call `self.http_method_bot_allowed` for error handline.
+
+    If the `htmx` request attrobute is not set or is False, then fall back to the original dispatch.
+    """
+    if not getattr(request, "htmx", False):  # Not an HTMX aware request
+        return self._non_htmx_dispatch(request, *args, **kwargs)
+
+    # Allow different  allowed methods for htmx
+    allowed_names = getattr(self, "htmx_http_method_names", self.http_method_names)
+
+    if request.method.lower() in allowed_names:
+        handler = getattr(
+            self, f"htmx_{request.method.lower()}", getattr(self, request.method.lower(), self.http_method_not_allowed)
+        )
+    else:
+        handler = self.http_method_not_allowed
+    if not callable(handler):
+        handler = self.http_method_not_allowed
+    return handler(request, *args, **kwargs)
+
+
+class HTMXProcessMixin:
+    """Provide versions of the htmx_`<http_verb>` methods that will delegate to trigger specific methods.
+
+    Each http verb DELETE,GET,PATCH,POST,PUT's htmx_<verb> method will look at the request.htmx attriobute
+    to see if htmx_<verb>_<trigger_name>, htmx_<verb>_<trigger>, htmx_<verb>_<target> is a method and then pass
+    on to the first matching method. If no match is foumd, the `http_method_not_allowed` method is used instead.
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Initialise HTMX process mixin with context flags.
+
+        Keyword Parameters:
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
+        super().__init__(*args, **kwargs)
+        self._htmx_get_context_data = False
+        self._htmx_get_context_object_name = False
+        self._htmx_get_template_names = False
+
+    def htmx_elements(self):
+        """Iterate over possible htmx element sources."""
+        for attr in ["trigger_name", "trigger", "target"]:
+            if elem := getattr(self.request.htmx, attr, None):
+                elem = re.sub(r"[^A-Za-z0-9_]", "", elem).lower()
+                if settings.DEBUG:
+                    logger.debug(elem)
+                yield elem
+
+    def get_context_data_function(self, **kwargs):
+        """Return the first callable element-specific context handler."""
+        del kwargs
+        for elem in self.htmx_elements():
+            handler = getattr(self, f"get_context_data_{elem}", None)
+            if callable(handler):
+                return handler
+        return None
+
+    def get_context_data(self, **kwargs):
+        """Get context data being aware of htmx views."""
+        if not getattr(self.request, "htmx", False) or self._htmx_get_context_data:  # Default behaviour
+            return super().get_context_data(**kwargs)
+
+        # Look for a request specific to the element involved.
+        handler = self.get_context_data_function(**kwargs)
+        if handler is not None:
+            with temp_attr(self, "_htmx_get_context_data", True):
+                return handler(**kwargs)
+        return super().get_context_data(**kwargs)
+
+    def get_context_object_name(self, object_list):
+        """Get context object name being aware of htmx elements.
+
+        If the get_context_name_<element> method needs to call usper, it should set a keyword
+        argument, _default to be True to avoid a recursive loop.
+        """
+        if not getattr(self.request, "htmx", False) or self._htmx_get_context_object_name:  # Default behaviour
+            return super().get_context_object_name(object_list)
+
+        # Look for a request specific to the element involved.
+        for elem in self.htmx_elements():
+            for handler_name in (f"get_context_object_name_{elem}", f"get_context_object_name{elem}"):
+                if callable(handler := getattr(self, handler_name, None)):
+                    with temp_attr(self, "_htmx_get_context_object_name", True):
+                        return handler(object_list)
+            if sub_name := getattr(self, f"context_object_{elem}", False):
+                return sub_name
+
+        logger.debug("Super")
+
+        return super().get_context_object_name(object_list)
+
+    def get_template_names(self):
+        """Look for htmx specific templates."""
+        if not getattr(self.request, "htmx", False) or self._htmx_get_template_names:  # Default behaviour
+            return super().get_template_names()
+
+        # Look for a request specific to the element involved.
+        for elem in self.htmx_elements():
+            handler = getattr(self, f"get_template_names_{elem}", None)
+            if callable(handler):
+                if settings.DEBUG:
+                    logger.debug(f"Template_handler: {handler.__name__}")
+                with temp_attr(self, "_htmx_get_template_names", True):
+                    return handler()
+            sub_name = getattr(self, f"template_name_{elem}", False)
+            if sub_name:
+                if settings.DEBUG:
+                    logger.debug(f"Template_name: {sub_name}")
+                return sub_name
+        return super().get_template_names()
+
+    def htmx_delete(self, request, *args, **kwargs):
+        """Delegate HTMX DELETE requests.
+
+        Looks for the element that is related to the request by inspecting the `request.htmx` `trigger_name`, trigger
+        and target attributes in turn. If no matching `htmx_delete_<name>` methods are found, return the
+        `method_not_allowed` result instrad.
+        """
+        for elem in self.htmx_elements():
+            handler = getattr(self, f"htmx_delete_{elem}", None)
+            if callable(handler):
+                break
+        else:
+            handler = getattr(self, "delete", self.http_method_not_allowed)
+        if not callable(handler):
+            handler = self.http_method_not_allowed
+        if settings.DEBUG:
+            logger.debug(f"HTMX Method handler: {handler.__name__}")
+        return handler(request, *args, **kwargs)
+
+    def htmx_get(self, request, *args, **kwargs):
+        """Delegate HTMX GET requests.
+
+        Looks for the element that is related to the request by inspecting the `request.htmx` `trigger_name`, trigger
+        and target attributes in turn. If no matching `htmx_get_<name>` methods are found, return the
+        `method_not_allowed` result instrad.
+        """
+        for elem in self.htmx_elements():
+            handler = getattr(self, f"htmx_get_{elem}", None)
+            if callable(handler):
+                break
+        else:
+            handler = getattr(self, "get", self.http_method_not_allowed)
+        if not callable(handler):
+            handler = self.http_method_not_allowed
+        if settings.DEBUG:
+            logger.debug(f"HTMX Method handler: {handler.__name__}")
+        return handler(request, *args, **kwargs)
+
+    def htmx_patch(self, request, *args, **kwargs):
+        """Delegate HTMX PATCH requests.
+
+        Looks for the element that is related to the request by inspecting the `request.htmx` `trigger_name`, trigger
+        and target attributes in turn. If no matching `htmx_patch_<name>` methods are found, return the
+        `method_not_allowed` result instrad.
+        """
+        for elem in self.htmx_elements():
+            handler = getattr(self, f"htmx_patch_{elem}", None)
+            if callable(handler):
+                break
+        else:
+            handler = getattr(self, "patch", self.http_method_not_allowed)
+        if not callable(handler):
+            handler = self.http_method_not_allowed
+        if settings.DEBUG:
+            logger.debug(f"HTMX Method handler: {handler.__name__}")
+        return handler(request, *args, **kwargs)
+
+    def htmx_post(self, request, *args, **kwargs):
+        """Delegate HTMX POST requests.
+
+        Looks for the element that is related to the request by inspecting the `request.htmx` `trigger_name`, trigger
+        and target attributes in turn. If no matching `htmx_post_<name>` methods are found, return the
+        `method_not_allowed` result instrad.
+        """
+        for elem in self.htmx_elements():
+            handler = getattr(self, f"htmx_post_{elem}", None)
+            if callable(handler):
+                break
+        else:
+            handler = getattr(self, "post", self.http_method_not_allowed)
+        if not callable(handler):
+            handler = self.http_method_not_allowed
+        if settings.DEBUG:
+            logger.debug(f"HTMX Method handler: {handler.__name__}")
+        return handler(request, *args, **kwargs)
+
+    def htmx_put(self, request, *args, **kwargs):
+        """Delegate HTMX PUT requests.
+
+        Looks for the element that is related to the request by inspecting the `request.htmx` `trigger_name`, trigger
+        and target attributes in turn. If no matching `htmx_put_<name>` methods are found, return the
+        `method_not_allowed` result instrad.
+        """
+        for elem in self.htmx_elements():
+            handler = getattr(self, f"htmx_put_{elem}", None)
+            if callable(handler):
+                break
+        else:
+            handler = getattr(self, "put", self.http_method_not_allowed)
+        if not callable(handler):
+            handler = self.http_method_not_allowed
+        if settings.DEBUG:
+            logger.debug(f"HTMX Method handler: {handler.__name__}")
+        return handler(request, *args, **kwargs)
+
+
+class HTMXFormMixin(HTMXProcessMixin):
+    """Provide additional methods to adapt FormView and friends for htmx requests as well."""
+
+    def __init__(self, *args, **kwargs):
+        """Initialise HTMX form mixin with form validation flags.
+
+        Keyword Parameters:
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
+        super().__init__(*args, **kwargs)
+        self._htmx_form_valid = False
+        self._htmx_form_invalid = False
+
+    def form_valid(self, form):
+        """Look for HTMX form valid handlers.
+
+        If request.htmx is not set, then return the parent class form_valid, otherwise look for an element
+        specific htmx_form_valid_<name> method, or failing that just an htmx_form_valid meothd. Fnally,
+        give up and return the parent form_valid.
+
+        Notes:
+            htmx_form_valid* methods must not call super().form_valid - otherwise an infinite recursion happens!
+        """
+        if not getattr(self.request, "htmx", False) or self._htmx_form_valid:  # Non HTMX requests
+            return super().form_valid(form)
+        for elem in self.htmx_elements():
+            if settings.DEBUG:
+                logger.debug(f"Looking for htmx_form_valid_{elem}")
+            handler = getattr(self, f"htmx_form_valid_{elem}", False)
+            if handler and callable(handler):
+                with temp_attr(self, "_htmx_form_valid", True):
+                    return handler(form)
+        if callable(handler := getattr(self, "htmx_form_valid", False)):
+            with temp_attr(self, "_htmx_form_valid", True):
+                return handler(form)
+        return super().form_valid(form)
+
+    def form_invalid(self, form):
+        """Look for HTMX form valid handlers.
+
+        If request.htmx is not set, then return the parent class form_invalid, otherwise look for an element
+        specific htmx_form_invalid_<name> method, or failing that just an htmx_form_invalid meothd. Fnally,
+        give up and return the parent form_invalid.
+
+        Notes:
+            htmx_inform_valid* methods must not call super().form_valid - otherwise an infinite recursion happens!
+        """
+        if not getattr(self.request, "htmx", False) or self._htmx_form_invalid:  # Non HTMX requests
+            return super().form_invalid(form)
+
+        for elem in self.htmx_elements():
+            handler = getattr(self, f"htmx_form_invalid_{elem}", False)
+            if settings.DEBUG:
+                logger.debug(f"Looking for htmx_form_invalid_{elem}")
+            if handler and callable(handler):
+                with temp_attr(self, "_htmx_form_invalid", True):
+                    return handler(form)
+        if callable(handler := getattr(self, "htmx_form_invalid", False)):
+            with temp_attr(self, "_htmx_form_invalid", True):
+                return handler(form)
+        return super().form_invalid(form)
+
+
+def __getattr__(name):
+    """Lazily preserve the former linked-select view import path."""
+    if name == "LinkedSelectEndpointView":
+        # app imports
+        from .linked_selects import LinkedSelectEndpointView
+
+        return LinkedSelectEndpointView
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def _install_htmx_dispatch(view_class=View):
+    """Install the HTMX-aware dispatch function idempotently."""
+    if not hasattr(view_class, "_non_htmx_dispatch"):
+        setattr(view_class, "_non_htmx_dispatch", view_class.dispatch)
+    setattr(view_class, "dispatch", dispatch)
+
+
+_install_htmx_dispatch()

htmx_views/widgets.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+"""Create an htmx backed linked select widget."""
+
+# Python imports
+from urllib.parse import urlencode
+
+# Django imports
+from django.core.exceptions import ImproperlyConfigured
+from django.forms.widgets import Select
+from django.urls import reverse_lazy
+from django.utils.text import format_lazy
+
+# app imports
+from ._optional import get_ajax_select_registry
+
+registry = get_ajax_select_registry()
+
+
+class HTMXSelectWidget(Select):
+    """Override SelectWidget to allow the options to be updated on a linked change.
+
+    This uses the machinery of django-ajax-select lookups to derive the list of options,
+    but uses htmx for the transfer mechanism.
+    """
+
+    # temmplate_name = "htmx_views/widgets/select.html"
+
+    def __init__(self, lookup_channel, parent=None, *args, **kwargs):
+        """Extract linked Select.
+
+        Args:
+            lookup_channel (str):
+                The name of an ajax_select lookup channel
+        """
+        try:
+            self.lookup = registry.get(lookup_channel)
+        except ImproperlyConfigured as error:
+            raise ImproperlyConfigured(
+                f"Attempting to use a htmx_views widget with lookup channel {lookup_channel} that does not exist."
+            ) from error
+
+        self.lookup_channel = lookup_channel
+        if parent is None:
+            parent = getattr(self.lookup, "parameter_name", None)
+        if parent is None:
+            raise ImproperlyConfigured(
+                f"Creating an htmx_views widget for {lookup_channel} without knowing the trigger."
+            )
+        self.parent_name = parent
+        endpoint = reverse_lazy("htmx_views:select", args=(self.lookup_channel,))
+        query_string = urlencode({"_htmx_parent": self.parent_name})
+        attrs = dict(kwargs.pop("attrs", {}))
+        attrs.update(
+            {
+                "hx-get": format_lazy("{}?{}", endpoint, query_string),
+                "hx-trigger": f"change from:#id_{self.parent_name}",
+                "hx-include": f"#id_{self.parent_name}",
+            }
+        )
+        kwargs["attrs"] = attrs
+
+        super().__init__(*args, **kwargs)
+
+    def get_context(self, name, value, attrs):
+        """Customise the context."""
+        attrs = dict(attrs or {})
+        attrs["hx-target"] = f"#id_{name}"
+        return super().get_context(name, value, attrs)