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

django_htmx_plus/http.py

@@ -0,0 +1,47 @@
+from typing import List
+
+from django.http import HttpResponse
+
+
+class HtmxResponse(HttpResponse):
+    """An HTTP 204 response that carries HTMX trigger events.
+
+    Returns a ``204 No Content`` status and populates the ``HX-Trigger``
+    response header with one or more comma-separated event names, causing
+    HTMX to fire those events on the client and trigger any listening elements
+    to refresh without a full page reload.
+    """
+
+    def __init__(self, triggers: List[str], *args, **kwargs):
+        """Initialise the response with the given trigger event names.
+
+        Args:
+            triggers (List[str]): Event names to include in the ``HX-Trigger``
+                response header.
+            *args: Additional positional arguments forwarded to ``HttpResponse``.
+            **kwargs: Additional keyword arguments forwarded to ``HttpResponse``.
+        """
+        super(HtmxResponse, self).__init__(*args, **kwargs)
+        self.status_code = 204
+        self.headers["HX-Trigger"] = ",".join(triggers)
+
+
+class HtmxRedirectResponse(HttpResponse):
+    """An HTTP response that instructs HTMX to perform a client-side redirect.
+
+    Populates the ``HX-Redirect`` response header with the supplied destination
+    URL, causing HTMX to navigate the browser to that URL without a traditional
+    HTTP redirect status code.
+    """
+
+    def __init__(self, destination: str, *args, **kwargs):
+        """Initialise the response with the redirect destination URL.
+
+        Args:
+            destination (str): The URL to redirect the client to via the
+                ``HX-Redirect`` response header.
+            *args: Additional positional arguments forwarded to ``HttpResponse``.
+            **kwargs: Additional keyword arguments forwarded to ``HttpResponse``.
+        """
+        super(HtmxRedirectResponse, self).__init__(*args, **kwargs)
+        self.headers["HX-Redirect"] = destination

django_htmx_plus/middleware.py

@@ -0,0 +1,70 @@
+import json
+from django.contrib.messages import get_messages
+
+
+class HtmxMessagesMiddleware:
+    """Middleware that forwards Django messages to HTMX via the HX-Trigger header.
+
+    Intercepts HTMX requests and appends any pending Django messages to the
+    ``HX-Trigger`` response header as a ``messages`` key, allowing the
+    client-side HTMX event system to display them without a full page reload.
+    """
+
+    def __init__(self, get_response):
+        """Initialize the middleware.
+
+        Args:
+            get_response: The next middleware or view in the chain.
+        """
+        self.get_response = get_response
+
+    def __call__(self, request):
+        """Process the request and attach messages to the HX-Trigger header.
+
+        Args:
+            request: The incoming HTTP request.
+
+        Returns:
+            HttpResponse: The response with the ``HX-Trigger`` header updated
+            to include any pending Django messages when the request was made
+            by HTMX and the response is not a redirect.
+        """
+        response = self.get_response(request)
+
+        # The HX-Request header indicates that the request was made with HTMX
+        if "HX-Request" not in request.headers:
+            return response
+
+        # Ignore redirections because HTMX cannot read the headers
+        if 300 <= response.status_code < 400:
+            return response
+
+        # Extract the messages
+        messages = [{"message": message.message, "tags": message.tags} for message in get_messages(request)]
+        if not messages:
+            return response
+
+        # Get the existing HX-Trigger that could have been defined by the view
+        hx_trigger = response.headers.get("HX-Trigger")
+
+        if hx_trigger is None:
+            # If the HX-Trigger is not set, start with an empty object
+            hx_trigger = {}
+        elif hx_trigger.startswith("{"):
+            # If the HX-Trigger uses the object syntax, parse the object
+            hx_trigger = json.loads(hx_trigger)
+        else:
+            # If the HX-Trigger uses the string syntax, convert to the object syntax
+            triggers = hx_trigger.split(",")
+            hx_trigger = {}
+            for trigger in triggers:
+                hx_trigger[trigger] = True
+
+        # Add the messages array in the HX-Trigger object
+        hx_trigger["messages"] = messages
+
+        # Add or update the HX-Trigger
+        response.headers["HX-Trigger"] = json.dumps(hx_trigger)
+
+        return response
+

django_htmx_plus/mixins.py

@@ -0,0 +1,41 @@
+from django_htmx_plus.http import HtmxResponse
+from django.contrib import messages
+from typing import List
+
+
+class HtmxFormResponseMixin:
+    """A mixin that provides a trigger-aware HTMX response for successful form submissions.
+
+    Mix this class into any ``FormView`` or ``CreateView`` subclass to replace the
+    default redirect response with an :class:`~django_htmx_plus.http.HtmxResponse`
+    that carries one or more ``HX-Trigger`` events, allowing the page to react
+    without a full navigation.
+
+    Attributes:
+        valid_triggers (List[str]): Event names included in the ``HX-Trigger`` header
+            of the response returned after a successful form submission.
+    """
+
+    valid_triggers: List[str] = []
+    success_message: str = ''
+
+    def form_valid(self, form):
+        """Save the form and return a trigger-aware HTMX response.
+
+        Calls ``form.save()`` and then returns an :class:`~django_htmx_plus.http.HtmxResponse`
+        that sends all events listed in :attr:`valid_triggers` via the ``HX-Trigger``
+        response header, prompting any listening HTMX elements to refresh.
+
+        Args:
+            form (forms.ModelForm): A bound and validated Django form instance.
+
+        Returns:
+            HtmxResponse: A 204 response containing the ``HX-Trigger`` header populated
+            with the events defined in :attr:`valid_triggers`.
+        """
+        form.save()
+
+        if self.success_message:
+            messages.success(self.request, self.success_message)
+
+        return HtmxResponse(self.valid_triggers)

django_htmx_plus/static/django_htmx_plus/django-htmx-plus.js

@@ -0,0 +1,39 @@
+import {Modal, Offcanvas} from 'bootstrap';
+
+const dialogs = {}
+
+for (const element of document.querySelectorAll('[data-htmx-plus-modal]')) {
+    dialogs[element.dataset.htmxPlusModal] = new Modal(element);
+}
+
+for (const element of document.querySelectorAll('[data-htmx-plus-offcanvas]'))  {
+    dialogs[element.dataset.htmxPlusOffcanvas] = new Offcanvas(element);
+}
+
+htmx.on("htmx:afterSwap", (e) => {
+    // Response targeting #dialog => show the modal
+    const element_id = e.detail.target.id;
+
+    if(element_id in dialogs) {
+        dialogs[element_id].show();
+    }
+});
+
+htmx.on("htmx:beforeSwap", (e) => {
+    // Empty response targeting #dialog => hide the modal
+    const element_id = e.detail.target.id;
+
+    if(element_id in dialogs && !e.detail.xhr.response) {
+        dialogs[element_id].hide();
+        e.detail.shouldSwap = false;
+    }
+});
+
+htmx.on("hidden.bs.modal", (e) => {
+    // This resets modal body to ""
+    document.getElementById(e.target.id).firstElementChild.innerHTML = "";
+})
+
+htmx.on("hidden.bs.offcanvas", (e) => {
+    console.log("offcanvas", e);
+})

django_htmx_plus/templates/cotton/icons/chevron_down.html

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+	 stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+	 class="icon icon-tabler icons-tabler-outline icon-tabler-chevron-down {{ add_class }}" {{ attrs }}>
+	<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
+	<path d="M6 9l6 6l6 -6"/>
+</svg>

django_htmx_plus/templates/cotton/icons/chevron_left.html

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+	 stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+	 class="icon icon-tabler icons-tabler-outline icon-tabler-chevron-left {{ add_class }}" {{ attrs }}>
+	<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
+	<path d="M15 6l-6 6l6 6"/>
+</svg>

django_htmx_plus/templates/cotton/icons/chevron_right.html

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+	 stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+	 class="icon icon-tabler icons-tabler-outline icon-tabler-chevron-right {{ add_class }}" {{ attrs }}>
+	<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
+	<path d="M9 6l6 6l-6 6"/>
+</svg>

django_htmx_plus/templates/cotton/icons/chevron_up.html

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+	 stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+	 class="icon icon-tabler icons-tabler-outline icon-tabler-chevron-up {{ add_class }}" {{ attrs }}>
+	<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
+	<path d="M6 15l6 -6l6 6"/>
+</svg>

django_htmx_plus/templates/cotton/tables/head.html

@@ -0,0 +1,5 @@
+<thead>
+	<tr>
+		{{ slot }}
+	</tr>
+</thead>

django_htmx_plus/templates/cotton/tables/header_cell.html

@@ -0,0 +1,15 @@
+<th class="cursor-pointer {{ add_class }}" hx-get="{{ path }}{% if page_obj %}?page={{ page_obj.number }}&{% else %}?{% endif %}{% if filter_query %}{{ filter_query }}&{% endif %}order_by={% if name == order_by %}-{{ name }}{% else %}{{ name }}{% endif %}"
+	hx-target="{{ target_id }}">
+	<div class="d-flex">
+		<div class="flex-grow-1 align-bottom mt-1">
+			{{ slot }}
+		</div>
+		{% if order_by %}
+			{% if name == order_by %}
+				<c-icons.chevron_up add_class="ms-1"/>
+			{% elif "-"|add:name == order_by %}
+				<c-icons.chevron_down add_class="ms-1"/>
+			{% endif %}
+		{% endif %}
+	</div>
+</th>

django_htmx_plus/templates/cotton/tables/htmx_table.html

@@ -0,0 +1,22 @@
+{% load cotton_extras %}
+<div class="htmx-table-wrap">
+<table class="{{class}}">
+	<thead>
+		{% for field in fields.keys %}
+			<c-tables.header_cell name="{{ field }}">{% if field in fields.labels %}{{ fields.labels|get_key_value:field }}{% else %}{{field|capfirst}}{% endif %}</c-tables.header_cell>
+		{% endfor %}
+	</thead>
+	<tbody>
+	{% for item in objects %}
+		<tr>
+			{% for field in fields.keys %}
+				<td>{{ item|get_key_value:field }}</td>
+			{% endfor %}
+		</tr>
+	{% endfor %}
+	</tbody>
+</table>
+</div>
+{% if paginator %}
+<c-tables.pager />
+{% endif %}

django_htmx_plus/templates/cotton/tables/pager.html

@@ -0,0 +1,35 @@
+
+<div class="d-flex justify-content-center justify-content-sm-between">
+	<div class="align-items-center">
+		<p class="m-0 text-secondary">Showing <strong>{{ page_obj.start_index }} to {{ page_obj.end_index }}</strong> of
+			<strong>{{ page_obj.paginator.count }} entries</strong></p>
+	</div>
+	<div class="justify-content-end">
+		<ul class="pagination" hx-target="{{ target_id }}">
+			<li class="page-item {% if not page_obj.has_previous %}disabled{% endif %}">
+				<button type="button" class="page-link"
+						{% if page_obj.has_previous %}hx-get="{{ request.path }}?page={{ page_obj.previous_page_number }}&{{ query }}"{% endif %}
+						tabindex="-1" aria-disabled="true">
+					<c-icons.chevron_left/>
+				</button>
+			</li>
+			{% for page in page_range %}
+				<li class="page-item {% if page_obj.number == page %}active{% endif %}">
+					{% if page == page_obj.paginator.ELLIPSIS %}
+						<span class="page-link h-100">{{ page }}</span>
+					{% else %}
+						<button type="button" class="h-100 page-link {% if page_obj.number == page %}active{% endif %}"
+								hx-get="{{ request.path }}?page={{ page }}&{{ query }}">{{ page }}</button>
+					{% endif %}
+				</li>
+			{% endfor %}
+			<li class="page-item {% if not page_obj.has_next %}disabled{% endif %}">
+				<button type="button" class="page-link"
+						{% if page_obj.has_next %}hx-get="{{ request.path }}?page={{ page_obj.next_page_number }}&{{ query }}"{% endif %}
+						tabindex="-1" aria-disabled="true">
+					<c-icons.chevron_right/>
+				</button>
+			</li>
+		</ul>
+	</div>
+</div>

django_htmx_plus/templatetags/cotton_extras.py

@@ -0,0 +1,17 @@
+from django import template
+from typing import Dict, Any
+
+
+register = template.Library()
+
+@register.filter(name="get_attr")
+def get_attr(obj, attr_name):
+    if not hasattr(obj, attr_name):
+        return ''
+
+    return getattr(obj, attr_name)
+
+
+@register.filter(name="get_key_value")
+def get_key_value(obj: Dict[str, Any], key: str):
+    return obj.get(key, None)

django_htmx_plus/templatetags/django_htmx_plus.py

@@ -0,0 +1,16 @@
+from django.utils.safestring import SafeString
+from django.utils.html import format_html
+from django.templatetags.static import static
+from django.template import Library, Context
+
+register = Library()
+
+
+@register.simple_tag(takes_context=True)
+def htmx_plus_script(context: Context) -> str:
+    parts = [
+        static("django_htmx_plus/django-htmx-plus.js"),
+        (context.get("nonce", None) or "")
+    ]
+
+    return format_html('<script src="{}" type="module"{}></script>', *parts)

django_htmx_plus/types.py

@@ -0,0 +1,21 @@
+from enum import StrEnum
+
+class Filter(StrEnum):
+    EQ = 'exact'
+    IEQ = 'iexact'
+    GT = 'gt'
+    GTE = 'gte'
+    LT = 'lt'
+    LTE = 'lte'
+    LIKE = 'like'
+    ILIKE = 'ilike'
+    CS = 'cs'
+    ICS = 'ics'
+    IN = 'in'
+    NL = 'isnull'
+    RNG = 'range'
+    EW = 'endswith'
+    IEW = 'iendswith'
+    SW = 'startswith'
+    ISW = 'istartswith'
+    SCH = 'search'

django_htmx_plus/utils.py

@@ -0,0 +1,111 @@
+import ast
+from typing import List, Dict, Any, Tuple
+
+from django_htmx_plus.types import Filter
+
+
+def build_filter_dict(query_params: Dict[str, Any], allowed_fields: Tuple[str, ...] | None) -> dict:
+    """Build a filter dictionary from query parameters, restricted to allowed fields.
+
+    Parses query parameters of the form ``field_name.filter_type=value`` and
+    converts them into a Django ORM-compatible filter dict. Only fields present
+    in ``allowed_fields`` are processed; unknown filter suffixes are silently
+    dropped rather than forwarded to the ORM.
+
+    The ``field_name`` portion is the *root* field name only — traversal via
+    ``__`` within the field name segment is not permitted. This prevents callers
+    from bypassing the allowlist via related-model lookups (e.g.
+    ``related__secret.eq=value``).
+
+    Args:
+        query_params (dict): A dictionary of raw query parameters, typically
+            ``request.GET``.
+        allowed_fields (Tuple[str, ...] | None): A tuple of permitted field names.
+            Pass ``("__all__",)`` or an empty tuple/``None`` to allow all fields.
+
+    Returns:
+        dict: A dictionary suitable for passing directly to ``QuerySet.filter()``.
+    """
+    filter_dict = {}
+    unrestricted = not allowed_fields or "__all__" in allowed_fields
+    for key, value in query_params.items():
+        if "." in key:
+            field_name, filter_type = key.split(".", 1)
+            # Block traversal: field_name must be a plain field, not a __ path
+            if "__" in field_name:
+                continue
+            if unrestricted or field_name in allowed_fields:
+                if filter_type.upper() in Filter.__members__:
+                    filter_value = Filter.__members__[filter_type.upper()].value
+                    if isinstance(value, str):
+                        try:
+                            filter_dict[f"{field_name}__{filter_value}"] = ast.literal_eval(value)
+                        except ValueError:
+                            filter_dict[f"{field_name}__{filter_value}"] = value
+                    else:
+                        filter_dict[f"{field_name}__{filter_value}"] = value
+                # Unknown filter suffixes are silently ignored instead of being
+                # forwarded to the ORM with an invalid key.
+    return filter_dict
+
+
+def build_query_str(query_params: dict) -> str:
+    """Build a URL query string from filter-style query parameters.
+
+    Iterates over ``query_params`` and includes only entries whose key contains
+    a ``.`` (i.e. ``field_name.filter_type`` pairs). The ``order_by`` and other
+    plain parameters are intentionally excluded.
+
+    Args:
+        query_params (dict): A dictionary of raw query parameters, typically
+            ``request.GET``.
+
+    Returns:
+        str: An ampersand-joined query string of the form
+            ``field.filter=value&field2.filter=value2``, or an empty string if
+            no matching parameters are present.
+    """
+    items = []
+    for key, value in query_params.items():
+        if "." in key:
+            items.append(f"{key}={value}")
+    return "&".join(items)
+
+def build_filters_template_dict(filter: dict) -> dict:
+    """Convert an ORM filter dict into a template-friendly mapping.
+
+    Strips the Django ORM lookup suffix (everything from the first ``__``
+    onward) from each key so that templates receive plain field names as keys.
+    For example, ``{"name__icontains": "Alice"}`` becomes ``{"name": "Alice"}``.
+
+    Args:
+        filter (dict): A dictionary of ORM filter expressions as returned by
+            :func:`build_filter_dict`.
+
+    Returns:
+        dict: A dictionary mapping plain field names to their filter values.
+    """
+    results = {}
+    for key, value in filter.items():
+        results[key.split("__")[0]] = value
+    return results
+
+def split_and_strip(content: str) -> List[str]:
+    """Split and normalise a multi-line string into a list of non-empty lines.
+
+    Strips leading/trailing spaces from each line, normalises Windows-style
+    line endings (``\\r\\n``) to Unix-style (``\\n``), removes non-breaking
+    space characters (``\\xa0`` and ``\\xc2``), and discards any lines that are
+    empty after stripping.
+
+    Args:
+        content (str): The raw multi-line string to process.
+
+    Returns:
+        List[str]: A list of cleaned, non-empty lines from ``content``.
+    """
+    lines = [
+        line.strip(" ").replace("\xa0", "").replace("\xc2", "")
+        for line in content.strip(" ").replace("\r\n", "\n").split("\n")
+    ]
+    return [line for line in lines if line]

django_htmx_plus/views.py

@@ -0,0 +1,165 @@
+from django.views.generic import ListView
+from typing import Tuple
+from urllib.parse import urlencode
+
+from django_htmx_plus.utils import build_filter_dict, build_query_str, build_filters_template_dict
+
+
+class HtmxListView(ListView):
+    """A Django ListView with HTMX support for filtering, sorting, and pagination.
+
+    Extends Django's ListView to provide seamless HTMX integration, including
+    dynamic filtering, column-based ordering, and elided pagination with query
+    string preservation.
+
+    Attributes:
+        target_id (str): The HTML element ID that HTMX will target for partial updates.
+        fields (Tuple[str, ...]): A tuple of model field names to include in the queryset
+            values. Use ``("__all__",)`` or leave empty to return full model instances.
+    """
+
+    target_id = ""
+    fields: Tuple[str, ...] = ()
+    labels: {}
+
+    def __init__(self):
+        """Initialise instance-level defaults for filter, query, and ordering state.
+
+        Sets safe default values so that attributes are always defined, even if
+        :meth:`setup` has not yet been called (e.g. during class introspection or
+        testing). All values are overwritten by :meth:`setup` on every real request.
+        """
+        super().__init__()
+        self.filter = {}
+        self.query = ""
+        self.filter_query = ""
+        self.order_by = "pk"
+
+    def setup(self, request, *args, **kwargs):
+        """Initialize view attributes from the incoming request.
+
+        Parses query parameters to build filter dictionaries, query strings, and
+        the active ordering field. Falls back to ``"pk"`` if no ordering is specified.
+
+        Args:
+            request: The incoming HTTP request object.
+            *args: Additional positional arguments passed to the parent ``setup``.
+            **kwargs: Additional keyword arguments passed to the parent ``setup``.
+        """
+        super(HtmxListView, self).setup(request, *args, **kwargs)
+        self.filter = build_filter_dict(request.GET, self.fields)
+        self.query = build_query_str(request.GET)
+        self.filter_query = self.query
+        self.order_by = getattr(self, "order_by", None)
+
+        if "order_by" in request.GET:
+            candidate = request.GET.get('order_by')
+            if self._is_order_by_allowed(candidate):
+                self.order_by = candidate
+
+        if not self.order_by:
+            self.order_by = "pk"
+
+        self.query += f"&order_by={self.order_by}"
+
+    def get_queryset(self):
+        """Return the filtered and ordered queryset for the view.
+
+        Applies any active filters from ``self.filter`` to the base queryset and
+        orders the result by ``self.order_by``. When ``fields`` is non-empty and
+        does not contain ``"__all__"``, the queryset is returned as a
+        ``ValuesQuerySet`` restricted to those fields, ensuring that columns not
+        listed in ``fields`` are never fetched from the database.
+
+        Returns:
+            QuerySet: A filtered and ordered queryset, or a ``ValuesQuerySet``
+            limited to ``self.fields`` when an explicit field list is provided.
+        """
+        qs = super(HtmxListView, self).get_queryset()
+
+        if hasattr(self, 'filter') and self.filter:
+            qs = qs.filter(**self.filter)
+        if hasattr(self, 'order_by') and self.order_by:
+            qs = qs.order_by(self.order_by)
+
+        if not self.fields or "__all__" in self.fields:
+            return qs
+
+        return qs.values(*self.fields)
+
+    def _is_order_by_allowed(self, order_by: str) -> bool:
+        """Check whether a user-supplied ordering field is permitted.
+
+        The field name is extracted by stripping a leading ``-`` (descending
+        indicator). Only the *root* segment (the part before the first ``__``)
+        is checked against ``self.fields``, so callers cannot bypass the
+        allowlist via related-model traversal (e.g. ``allowed_field__secret``).
+
+        Args:
+            order_by (str): The raw ``order_by`` value from the query string,
+                optionally prefixed with ``-`` for descending order.
+
+        Returns:
+            bool: ``True`` if the field is permitted or no allowlist is active,
+                ``False`` otherwise.
+        """
+        if not self.fields or "__all__" in self.fields:
+            return True
+        field = order_by.lstrip('-')
+        root_field = field.split('__')[0]
+        return root_field in self.fields
+
+    def get_context_data(self, **kwargs):
+        """Build and return the template context dictionary.
+
+        Adds HTMX- and pagination-related context variables, including the current
+        query string (without the ``page`` parameter), elided page range, ordering
+        state, request path, and active filters.
+
+        Args:
+            **kwargs: Additional keyword arguments forwarded to the parent
+                ``get_context_data``.
+
+        Returns:
+            dict: The context dictionary containing the following extra keys:
+
+            - ``query_params`` (str): URL-encoded query string excluding ``page``.
+            - ``page_range`` (iterator): Elided page range (only present when
+              ``paginate_by`` is set).
+            - ``order_by`` (str): The currently active ordering field.
+            - ``path`` (str): The current request path.
+            - ``target_id`` (str): The HTMX target element ID.
+            - ``query`` (str): Full query string including the ``order_by`` parameter.
+            - ``filter_query`` (str): Query string containing only filter parameters.
+            - ``filters`` (dict): Template-ready representation of active filters.
+        """
+        context = super().get_context_data(**kwargs)
+        query_params = {p: v for p, v in self.request.GET.items() if p != 'page'}
+        context["query_params"] = urlencode(query_params, doseq=True)
+
+        if hasattr(self, 'paginate_by') and self.paginate_by:
+            if not hasattr(self, 'elided_each_side'):
+                self.elided_each_side = 1
+
+            if not hasattr(self, 'elided_ends'):
+                self.elided_ends = 1
+
+            context["page_range"] = context["paginator"].get_elided_page_range(
+                number=context["page_obj"].number, on_each_side=self.elided_each_side, on_ends=self.elided_ends
+            )
+            context["paginator"].allow_empty_first_page = True
+
+        context["order_by"] = self.order_by
+        context["path"] = self.request.path
+        context["target_id"] = self.target_id
+        context["query"] = self.query
+        context["filter_query"] = self.filter_query
+        context["filters"] = build_filters_template_dict(self.filter)
+
+        fields = {
+            "keys": self.fields,
+            "labels": self.labels,
+        }
+        context["fields"] = fields
+
+        return context

django_htmx_plus-0.1.0.dist-info/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Davis
+
+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_plus-0.1.0.dist-info/METADATA

@@ -0,0 +1,361 @@
+Metadata-Version: 2.3
+Name: django-htmx-plus
+Version: 0.1.0
+Summary: django-htmx plus some extras
+License: MIT
+Author: Tim Davis
+Author-email: binary.god@gmail.com
+Requires-Python: >=3.11,<4
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: django-cotton (>=2.6.2,<3.0.0)
+Requires-Dist: django-htmx (>=1.27.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+# django-htmx-plus
+
+A Django utility library that extends [django-htmx](https://github.com/adamchainz/django-htmx) and [django-cotton](https://github.com/wrabit/django-cotton) with ready-made views, mixins, middleware, response helpers, and Cotton components for building HTMX-powered list views with filtering, sorting, and pagination.
+
+This package was created for my own projects but it was handy enough to share, I learned how to use HTMX with Django and Boostrap Modals from the following two posts from [Josh Karamuth](https://www.linkedin.com/in/josh-karamuth/): 
+* [How to show a modal in Django + HTMX](https://joshkaramuth.com/blog/django-htmx-modal/)
+* [Show Django forms inside a modal using HTMX](https://joshkaramuth.com/blog/django-htmx-modal-forms/)
+
+---
+
+## Features
+
+- **`HtmxResponse`** – a 204 No Content response that fires `HX-Trigger` events on the client.
+- **`HtmxRedirectResponse`** – a response that sends an `HX-Redirect` header to navigate the browser.
+- **`HtmxMessagesMiddleware`** – automatically forwards Django messages to the client via the `HX-Trigger` header on every HTMX request.
+- **`HtmxFormResponseMixin`** – a `FormView`/`CreateView` mixin that replaces the success redirect with an HTMX trigger response.
+- **`HtmxListView`** – a `ListView` subclass with built-in URL-based filtering, column sorting, and elided pagination.
+- **Filter helpers** – parse `field.filter_type=value` query parameters safely into Django ORM filter dicts.
+- **Cotton components** – drop-in table, header cell, and pager components styled for Bootstrap 5.
+- **Template filters** – `get_attr` and `get_key_value` for accessing object attributes and dict values in templates.
+- **Built-in JavaScript helper** – a `django-htmx-plus.js` ES module that wires Bootstrap 5 Modals and Offcanvases to HTMX swap events, with a `{% htmx_plus_script %}` template tag to include it.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- Django (any version compatible with the above)
+- [django-htmx](https://github.com/adamchainz/django-htmx) ≥ 1.27
+- [django-cotton](https://github.com/wrabit/django-cotton) ≥ 2.6
+
+---
+
+## Installation
+
+```bash
+pip install django-htmx-plus
+```
+
+Add to `INSTALLED_APPS` and configure middleware in `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_htmx",
+    "django_cotton",
+    "django_htmx_plus",
+]
+
+MIDDLEWARE = [
+    # ...
+    "django_htmx.middleware.HtmxMiddleware",        # required by django-htmx
+    "django_htmx_plus.middleware.HtmxMessagesMiddleware",
+]
+```
+
+---
+
+## Usage
+
+### HtmxResponse
+
+Return a `204 No Content` response that triggers one or more HTMX events on the client:
+
+```python
+from django_htmx_plus.http import HtmxResponse
+
+def my_view(request):
+    # ... do some work ...
+    return HtmxResponse(triggers=["itemUpdated", "refreshStats"])
+```
+
+The response sets `HX-Trigger: itemUpdated,refreshStats`, which HTMX picks up to re-fetch any elements listening for those events.
+
+---
+
+### HtmxRedirectResponse
+
+Instruct HTMX to navigate the browser to a new URL without a traditional HTTP redirect:
+
+```python
+from django_htmx_plus.http import HtmxRedirectResponse
+
+def my_view(request):
+    return HtmxRedirectResponse(destination="/dashboard/")
+```
+
+---
+
+### HtmxMessagesMiddleware
+
+Once the middleware is installed, any Django message added during an HTMX request is automatically serialised into the `HX-Trigger` header as a `messages` key:
+
+```json
+{
+  "messages": [
+    {"message": "Record saved.", "tags": "success"}
+  ]
+}
+```
+
+If the view already sets its own `HX-Trigger` header (either string or JSON object syntax), the middleware merges the messages in without overwriting existing triggers.
+
+Listen for the `messages` event in your HTMX setup to display the messages, for example:
+
+```javascript
+document.body.addEventListener("messages", (event) => {
+    event.detail.value.forEach(({message, tags}) => {
+        showToast(message, tags); // your toast implementation
+    });
+});
+```
+
+---
+
+### HtmxFormResponseMixin
+
+Mix into any `FormView` or `CreateView` to replace the default success redirect with an HTMX trigger response:
+
+```python
+from django.views.generic.edit import CreateView
+from django_htmx_plus.mixins import HtmxFormResponseMixin
+from myapp.models import Article
+from myapp.forms import ArticleForm
+
+class ArticleCreateView(HtmxFormResponseMixin, CreateView):
+    model = Article
+    form_class = ArticleForm
+    template_name = "articles/form.html"
+
+    valid_triggers = ["articleCreated"]
+    success_message = "Article created successfully."
+```
+
+After a valid submission, `form.save()` is called, an optional Django success message is queued, and an `HtmxResponse` carrying `articleCreated` in `HX-Trigger` is returned.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `valid_triggers` | `List[str]` | Events to include in `HX-Trigger` on success. |
+| `success_message` | `str` | Optional Django success message to queue. |
+
+---
+
+### HtmxListView
+
+A drop-in replacement for Django's `ListView` that adds URL-driven filtering, sorting, and elided pagination:
+
+```python
+from django.views.generic import ListView
+from django_htmx_plus.views import HtmxListView
+from myapp.models import Article
+
+class ArticleListView(HtmxListView):
+    model = Article
+    template_name = "articles/list.html"
+    paginate_by = 20
+    target_id = "#article-table"
+
+    # Restrict filtering and sorting to these fields only
+    fields = ("id", "title", "status", "created_at")
+
+    # Optional custom column labels
+    labels = {
+        "created_at": "Date Created",
+    }
+```
+
+#### URL-based filtering
+
+Filters are expressed as `field_name.filter_type=value` query parameters:
+
+| Filter key | Django lookup | Example |
+|---|---|---|
+| `eq` | `exact` | `status.eq=published` |
+| `ieq` | `iexact` | `title.ieq=hello` |
+| `gt` / `gte` / `lt` / `lte` | `gt` / `gte` / `lt` / `lte` | `views.gte=100` |
+| `like` / `ilike` | `like` / `ilike` | `title.ilike=django` |
+| `sw` / `isw` | `startswith` / `istartswith` | `title.sw=Django` |
+| `ew` / `iew` | `endswith` / `iendswith` | `title.ew=plus` |
+| `in` | `in` | `status.in=['draft','published']` |
+| `nl` | `isnull` | `deleted_at.nl=True` |
+| `rng` | `range` | `created_at.rng=['2024-01-01','2024-12-31']` |
+| `sch` | `search` | `body.sch=htmx` |
+
+Only fields listed in `fields` are accepted. Setting `fields = ("__all__",)` lifts the restriction.
+
+#### Sorting
+
+Add `order_by=field_name` (or `order_by=-field_name` for descending) to the query string. Only fields in `fields` are permitted.
+
+#### Context variables
+
+| Variable | Description |
+|---|---|
+| `query_params` | URL-encoded query string (without `page`). |
+| `page_range` | Elided page range for pagination controls. |
+| `order_by` | The currently active ordering field. |
+| `path` | The current request path. |
+| `target_id` | The HTMX target element ID. |
+| `query` | Full query string including `order_by`. |
+| `filter_query` | Query string containing only filter parameters. |
+| `filters` | Template-ready dict mapping plain field names to their filter values. |
+| `fields` | Dict with `keys` (field names) and `labels` (display names). |
+
+---
+
+### Cotton Table Components
+
+`django-htmx-plus` ships a set of [django-cotton](https://github.com/wrabit/django-cotton) components for rendering sortable, paginated HTMX tables with Bootstrap 5.
+
+#### `<c-tables.htmx_table />`
+
+Renders a full table with auto-generated sortable headers, rows, and an optional pager:
+
+```html
+{% load cotton_extras %}
+
+<c-tables.htmx_table class="table table-striped" />
+```
+
+The component uses the `fields`, `objects`, `order_by`, `path`, `filter_query`, `target_id`, `page_obj`, and `paginator` context variables provided automatically by `HtmxListView`.
+
+#### `<c-tables.header_cell name="field_name" />`
+
+Renders a single `<th>` with an `hx-get` attribute that toggles ascending/descending order and a chevron icon indicating the current sort direction:
+
+```html
+<c-tables.head>
+    <c-tables.header_cell name="title">Title</c-tables.header_cell>
+    <c-tables.header_cell name="created_at">Date</c-tables.header_cell>
+</c-tables.head>
+```
+
+#### `<c-tables.pager />`
+
+Renders a Bootstrap 5 pagination control with previous/next buttons and elided page numbers, all wired to `hx-get`.
+
+#### Icon components
+
+| Component | Description |
+|---|---|
+| `<c-icons.chevron_up />` | Up chevron (ascending sort indicator). |
+| `<c-icons.chevron_down />` | Down chevron (descending sort indicator). |
+| `<c-icons.chevron_left />` | Left chevron (previous page). |
+| `<c-icons.chevron_right />` | Right chevron (next page). |
+
+All icon components accept an optional `add_class` attribute to append extra CSS classes.
+
+---
+
+### Template filters
+
+Load the `cotton_extras` tag library in any template:
+
+```html
+{% load cotton_extras %}
+```
+
+| Filter | Description | Example |
+|---|---|---|
+| `get_attr` | Get an attribute from an object by name. | `{{ item\|get_attr:"title" }}` |
+| `get_key_value` | Get a value from a dict by key. | `{{ my_dict\|get_key_value:"name" }}` |
+
+---
+
+### Built-in JavaScript Helper
+
+`django-htmx-plus` ships a small ES module (`django-htmx-plus.js`) that integrates Bootstrap 5 **Modals** and **Offcanvases** with HTMX swap events, so they open and close automatically based on HTMX responses.
+
+#### How it works
+
+| Behaviour | Trigger |
+|---|---|
+| Show a Modal or Offcanvas | HTMX swaps content into the element → `htmx:afterSwap` fires and calls `.show()`. |
+| Hide a Modal or Offcanvas | HTMX receives an **empty** response targeting the element → `htmx:beforeSwap` fires, calls `.hide()`, and cancels the swap. |
+| Reset Modal body | Bootstrap's `hidden.bs.modal` event fires → the modal body is cleared to `""`. |
+
+#### Setup
+
+Mark your Bootstrap Modal root elements with `data-htmx-plus-modal="<id>"` and your Offcanvas root elements with `data-htmx-plus-offcanvas="<id>"`, where id is the id of the element that will be swapped,:
+
+```html
+<!-- Bootstrap Modal managed by django-htmx-plus -->
+<div class="modal fade" data-htmx-plus-modal="dialog">
+    <div id="dialog" class="modal-dialog">
+        <!-- Modal content will be swapped here by HTMX and shown/hidden by django-htmx-plus.js -->
+    </div>
+</div>
+
+<!-- Bootstrap Offcanvas managed by django-htmx-plus -->
+<div id="flyout" class="offcanvas offcanvas-end" data-htmx-plus-offcanvas="flyout">
+    <!-- Offcanvas content will be swapped here by HTMX and shown/hidden by django-htmx-plus.js -->
+</div>
+```
+
+Then point an HTMX element at the matching target ID:
+
+```html
+<button hx-get="/person/add/" hx-target="#dialog">
+    Add Person
+</button>
+```
+
+- When the response has content the modal/offcanvas is shown automatically.
+- When the server returns an empty `200` (or you use `HtmxResponse`) the modal/offcanvas is hidden automatically.
+
+#### Including the script
+
+Use the `{% htmx_plus_script %}` template tag to render the `<script>` tag. The script is loaded as an ES module and optionally forwards a CSP nonce if one is present in the template context:
+
+```html
+{% load django_htmx_plus %}
+
+<!-- Place near the bottom of your base template, after Bootstrap JS -->
+{% htmx_plus_script %}
+```
+
+This renders:
+
+```html
+<script src="/static/django_htmx_plus/django-htmx-plus.js" type="module"></script>
+```
+
+If a `nonce` variable is present in the template context it is automatically added as a `nonce="..."` attribute.
+
+> **Note:** The script imports `Modal` and `Offcanvas` from `bootstrap`, so Bootstrap 5 must be available as an ES module (e.g. via an import map or a bundler). If you load Bootstrap as a plain global script instead, adjust your bundler or import map accordingly.
+
+For example
+```html
+<script type="importmap">
+{
+  "imports": {
+	"@popperjs/core": "{% static '@popperjs/core/dist/esm/index.js' %}",
+	"bootstrap": "{% static 'bootstrap/js/index.esm.js' %}",
+  }
+}
+</script>
+```
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+

django_htmx_plus-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+django_htmx_plus/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_htmx_plus/http.py,sha256=lzZ2PVE9k2qZtbuDZcPyeG8aLCqYmcb5QgNS6QhrHZo,1906
+django_htmx_plus/middleware.py,sha256=m-pq12yzcWQFwLdPMk-MTxBGXIBx53CitMmZVhEbYno,2557
+django_htmx_plus/mixins.py,sha256=ZT4C8CSj7uo91JXkYeyTriK_sV_bZrUrPFV1IZucgNU,1558
+django_htmx_plus/static/django_htmx_plus/django-htmx-plus.js,sha256=ZOJzI2dhY9O-2QQ4PC6_MAB1KHg7poBOuTsPBXSA3cI,1084
+django_htmx_plus/templates/cotton/icons/chevron_down.html,sha256=4NLlMPH7H4YG-8ZxQQ5Az7Q1YFL8BQJ7mOTMsqukVLo,376
+django_htmx_plus/templates/cotton/icons/chevron_left.html,sha256=QvCAjjrYuq0e_6uxXMEUxZebimCqGrsKZddPCMGI9bk,377
+django_htmx_plus/templates/cotton/icons/chevron_right.html,sha256=OFCzCoi_gG_Mr05EFxFg7IqMQMK0MP0RwjSsaViZlzA,377
+django_htmx_plus/templates/cotton/icons/chevron_up.html,sha256=yiCe7xeunEPmWFyDv54A9NA4fA6U-EZFAXlQfSf57uE,375
+django_htmx_plus/templates/cotton/tables/head.html,sha256=OtiKc5vgLegpe2oMiCsf0i6LyENd5mOrp2gRkFMQ0nM,46
+django_htmx_plus/templates/cotton/tables/header_cell.html,sha256=XTAFnUCBzbxvk-qjC0foezyJE8bkW12xC5xkXVeo6ww,610
+django_htmx_plus/templates/cotton/tables/htmx_table.html,sha256=j_ihhZtv9iS9Kj0NIifVsCZ2x1EkcxQlpd73QgBDcX4,559
+django_htmx_plus/templates/cotton/tables/pager.html,sha256=yrlYxi0WBzwB6LzSceUzX7Wrm4TfeohrghWhn8x1l30,1576
+django_htmx_plus/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_htmx_plus/templatetags/cotton_extras.py,sha256=J9WN6DYU6OUDFUixkcPsbS7FjR1F4BXpjO6jKFkJ0mU,364
+django_htmx_plus/templatetags/django_htmx_plus.py,sha256=Jiif_JRJ0uUm6en04CVAWRWKY568L2WzeprH7jGRMGo,488
+django_htmx_plus/types.py,sha256=H62ZyhUPHXB4bvHTOPYxtH9woiPgrL5pYzJqwCpAKXs,369
+django_htmx_plus/utils.py,sha256=5lTLKdzyHAI4IBMz9SnKbWIhC1kvS72Ty0haI9KpQ5M,4597
+django_htmx_plus/views.py,sha256=3d888TxRnlJpBzAUTD2otIpBv_yjV1ayX72Qgf7GpRg,6831
+django_htmx_plus-0.1.0.dist-info/entry_points.txt,sha256=6wk1JJO2vDPZazpIf-Kx5Y1Mvh3VAYHGeAGJdz2JyIs,40
+django_htmx_plus-0.1.0.dist-info/LICENSE.md,sha256=katsVWhESJx9CgbnTX1Cw3ZNNxgIWM58vSrx6rUqluE,1065
+django_htmx_plus-0.1.0.dist-info/METADATA,sha256=0HHxqU0E0W9eZxMMdQXpgbjIYFZM-IK6QWg6SMMOp48,12519
+django_htmx_plus-0.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+django_htmx_plus-0.1.0.dist-info/RECORD,,

django_htmx_plus-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any

django_htmx_plus-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+tests=run_tests:main
+