feat: checkbox & radio filters (#1178)

Author: lukasvinclav

docs/filters/checkbox-radio.md

@@ -0,0 +1,106 @@
+---
+title: Checkbox and radio filters
+order: 6
+description: Enhance your Django admin with checkbox and radio button filters for model fields with choices, boolean fields, and related fields, providing a more intuitive and user-friendly filtering experience.
+---
+
+# Checkbox and radio filters
+
+Checkbox and radio filters display all options at once for easier selection, ideal for scenarios with a manageable number of filtering options. Unfold provides radio filters (single selection), checkbox filters (multiple selection), and specialized versions for different field types, making filtering more intuitive and accessible than traditional dropdowns.
+
+
+## Radio or checkbox filters for fields with choices
+
+Unfold provides specialized filters for model fields that have predefined choices. These filters enhance the user experience by displaying the choices as either radio buttons or checkboxes instead of the default dropdown.
+
+- These filters work with any model field that contains the `choices` property (typically `CharField` with choices)
+- The library supports both radio button inputs (`ChoicesRadioFilter`) and checkbox inputs (`ChoicesCheckboxFilter`)
+- When using the radio button filter (`ChoicesRadioFilter`), an "All" option is automatically added at the beginning of the list, allowing users to clear their selection
+- The checkbox filter (`ChoicesCheckboxFilter`) allows for selecting multiple options simultaneously
+
+These filters are particularly useful when you have a reasonable number of choices that would benefit from being all visible at once, rather than hidden in a dropdown menu.
+
+```python
+from unfold.contrib.filters.admin import ChoicesRadioFilter, ChoicesCheckboxFilter
+
+class SampleModelAdmin(ModelAdmin):
+    list_filter = [
+        ("status", ChoicesCheckboxFilter),
+        ("status", ChoicesRadioFilter)
+    ]
+```
+
+## Radio filter for BooleanField
+
+For boolean fields (`django.db.models.BooleanField`), Unfold provides a specialized filter called `BooleanRadioFilter`. This filter enhances the user experience by displaying the boolean options (Yes/No) as radio inputs, making it more intuitive and visually appealing compared to the default dropdown.
+
+The `BooleanRadioFilter` automatically includes an "All" option, allowing users to clear their selection and view all records regardless of the boolean field value. This is particularly useful when filtering through large datasets where you need to toggle between filtered and unfiltered views.
+
+Here's how to implement the `BooleanRadioFilter` in your admin configuration:
+
+```python
+from unfold.contrib.filters.admin import BooleanRadioFilter
+
+
+class SampleModelAdmin(ModelAdmin):
+    list_filter = [
+        ("is_active", BooleanRadioFilter)
+    ]
+```
+
+## Checkbox related field filter
+
+The `RelatedCheckboxFilter` is designed to work with foreign key relationships in your models. This filter displays related objects as a list of checkboxes, allowing users to select multiple values simultaneously. It's particularly useful when filtering by related models where you want to provide a more visual and accessible interface than a standard dropdown.
+
+```python
+from unfold.contrib.filters.admin import RelatedCheckboxFilter
+
+
+class SampleModelAdmin(ModelAdmin):
+    list_filter = [
+        ("country", RelatedCheckboxFilter)
+    ]
+```
+
+
+## Displaying all values in field
+
+The `AllValuesCheckboxFilter` provides a checkbox interface that automatically displays all distinct values found in the database column for the specified field. This filter functions similarly to Django's built-in `AllValuesFieldListFilter`, but enhances the user experience by presenting all available options as checkboxes instead of a dropdown menu. This approach allows users to see all possible values at once and select multiple options simultaneously, making it particularly useful for fields with a moderate number of distinct values that users frequently need to filter by.
+
+```python
+from unfold.contrib.filters.admin import AllValuesCheckboxFilter
+
+
+class SampleModelAdmin(ModelAdmin):
+    list_filter = [
+        ("option", AllValuesCheckboxFilter)
+    ]
+```
+
+## Custom checkbox or radio filter
+
+For custom filtering requirements, Unfold allows you to create your own checkbox or radio filters by extending the base filter classes. This gives you complete control over the filter's behavior, appearance, and the underlying query logic.
+
+You can create custom filters by extending either the `RadioFilter` or `CheckboxFilter` base classes, depending on whether you want single or multiple selection capability.
+
+```python
+from unfold.contrib.filters.admin import RadioFilter
+
+
+class CustomRadioFilter(RadioFilter):
+    title = _("Custom radio filter")
+    parameter_name = "query_param_in_uri"
+
+    def lookups(self, request, model_admin):
+        return [
+            ["option_1", _("Option 1")],
+            ["option_2", _("Option 2")],
+        ]
+
+    def queryset(self, request, queryset):
+        if self.value() not in EMPTY_VALUES:
+            # Here write custom query
+            return queryset.filter(your_field=self.value())
+
+        return queryset
+```

src/unfold/contrib/filters/admin/__init__.py

@@ -2,6 +2,15 @@
     AutocompleteSelectFilter,
     AutocompleteSelectMultipleFilter,
 )
+from unfold.contrib.filters.admin.choice_filters import (
+    AllValuesCheckboxFilter,
+    BooleanRadioFilter,
+    CheckboxFilter,
+    ChoicesCheckboxFilter,
+    ChoicesRadioFilter,
+    RadioFilter,
+    RelatedCheckboxFilter,
+)
 from unfold.contrib.filters.admin.datetime_filters import (
     RangeDateFilter,
     RangeDateTimeFilter,
@@ -11,7 +20,6 @@
     DropdownFilter,
     MultipleChoicesDropdownFilter,
     MultipleDropdownFilter,
-    MultipleRelatedDropdownFilter,
     RelatedDropdownFilter,
 )
 from unfold.contrib.filters.admin.numeric_filters import (
@@ -23,12 +31,19 @@
 from unfold.contrib.filters.admin.text_filters import FieldTextFilter, TextFilter
 
 __all__ = [
+    "AllValuesCheckboxFilter",
+    "BooleanRadioFilter",
+    "CheckboxFilter",
+    "ChoicesCheckboxFilter",
+    "ChoicesRadioFilter",
+    "MultipleRelatedCheckboxFilter",
+    "RadioFilter",
     "ChoicesDropdownFilter",
     "MultipleChoicesDropdownFilter",
     "DropdownFilter",
     "RelatedDropdownFilter",
     "MultipleDropdownFilter",
-    "MultipleRelatedDropdownFilter",
+    "RelatedCheckboxFilter",
     "FieldTextFilter",
     "TextFilter",
     "RangeDateFilter",

src/unfold/contrib/filters/admin/choice_filters.py

@@ -0,0 +1,134 @@
+from collections.abc import Generator
+from typing import Any
+
+from django.contrib import admin
+from django.contrib.admin.views.main import ChangeList
+from django.core.validators import EMPTY_VALUES
+from django.db.models import QuerySet
+from django.http import HttpRequest
+from django.utils.translation import gettext_lazy as _
+
+from unfold.contrib.filters.admin.mixins import MultiValueMixin, ValueMixin
+from unfold.contrib.filters.forms import CheckboxForm, HorizontalRadioForm, RadioForm
+
+
+class RadioFilter(admin.SimpleListFilter):
+    template = "unfold/filters/filters_field.html"
+    form_class = RadioForm
+    all_option = ["", _("All")]
+
+    def choices(self, changelist: ChangeList) -> tuple[dict[str, Any], ...]:
+        if self.all_option:
+            choices = [self.all_option, *self.lookup_choices]
+        else:
+            choices = self.lookup_choices
+
+        return (
+            {
+                "form": self.form_class(
+                    label=_(" By %(filter_title)s ") % {"filter_title": self.title},
+                    name=self.parameter_name,
+                    choices=choices,
+                    data={self.parameter_name: self.value()},
+                ),
+            },
+        )
+
+
+class CheckboxFilter(RadioFilter):
+    form_class = CheckboxForm
+    all_option = None
+
+
+class ChoicesMixin:
+    template = "unfold/filters/filters_field.html"
+
+    def choices(self, changelist: ChangeList) -> Generator[dict[str, Any], None, None]:
+        if self.all_option:
+            choices = [self.all_option, *self.field.flatchoices]
+        else:
+            choices = self.field.flatchoices
+
+        yield {
+            "form": self.form_class(
+                label=_(" By %(filter_title)s ") % {"filter_title": self.title},
+                name=self.lookup_kwarg,
+                choices=choices,
+                data={self.lookup_kwarg: self.value()},
+            ),
+        }
+
+
+class ChoicesRadioFilter(ValueMixin, ChoicesMixin, admin.ChoicesFieldListFilter):
+    form_class = RadioForm
+    all_option = ["", _("All")]
+
+
+class ChoicesCheckboxFilter(ValueMixin, ChoicesMixin, admin.ChoicesFieldListFilter):
+    form_class = CheckboxForm
+    all_option = None
+
+
+class BooleanRadioFilter(ValueMixin, admin.BooleanFieldListFilter):
+    template = "unfold/filters/filters_field.html"
+    form_class = HorizontalRadioForm
+    all_option = ["", _("All")]
+
+    def choices(self, changelist: ChangeList) -> Generator[dict[str, Any], None, None]:
+        choices = [
+            self.all_option,
+            *[
+                ("1", _("Yes")),
+                ("0", _("No")),
+            ],
+        ]
+
+        yield {
+            "form": self.form_class(
+                label=_(" By %(filter_title)s ") % {"filter_title": self.title},
+                name=self.lookup_kwarg,
+                choices=choices,
+                data={self.lookup_kwarg: self.value()},
+            ),
+        }
+
+
+class RelatedCheckboxFilter(MultiValueMixin, admin.RelatedFieldListFilter):
+    template = "unfold/filters/filters_field.html"
+    form_class = CheckboxForm
+
+    def queryset(self, request: HttpRequest, queryset: QuerySet) -> QuerySet:
+        if self.value() not in EMPTY_VALUES:
+            return super().queryset(request, queryset)
+
+        return queryset
+
+    def choices(self, changelist: ChangeList) -> Generator[dict[str, Any], None, None]:
+        yield {
+            "form": self.form_class(
+                label=_(" By %(filter_title)s ") % {"filter_title": self.title},
+                name=self.lookup_kwarg,
+                choices=self.lookup_choices,
+                data={self.lookup_kwarg: self.value()},
+            ),
+        }
+
+
+class AllValuesCheckboxFilter(MultiValueMixin, admin.AllValuesFieldListFilter):
+    template = "unfold/filters/filters_field.html"
+    form_class = CheckboxForm
+
+    def choices(self, changelist: ChangeList) -> Generator[dict[str, Any], None, None]:
+        choices = [[i, val] for i, val in enumerate(self.lookup_choices)]
+
+        if len(choices) == 0:
+            return
+
+        yield {
+            "form": self.form_class(
+                label=_(" By %(filter_title)s ") % {"filter_title": self.title},
+                name=self.lookup_kwarg,
+                choices=[[i, val] for i, val in enumerate(self.lookup_choices)],
+                data={self.lookup_kwarg: self.value()},
+            ),
+        }

src/unfold/contrib/filters/forms.py

@@ -1,14 +1,20 @@
 from django import forms
+from django.contrib.admin.options import HORIZONTAL
 from django.contrib.admin.widgets import AutocompleteSelect, AutocompleteSelectMultiple
 from django.db.models import Field as ModelField
-from django.forms import ChoiceField, ModelMultipleChoiceField, MultipleChoiceField
+from django.forms import (
+    ChoiceField,
+    ModelMultipleChoiceField,
+    MultipleChoiceField,
+)
 from django.http import HttpRequest
 from django.utils.translation import gettext_lazy as _
 
 from unfold.admin import ModelAdmin
-
-from ...widgets import (
+from unfold.widgets import (
     INPUT_CLASSES,
+    UnfoldAdminCheckboxSelectMultiple,
+    UnfoldAdminRadioSelectWidget,
     UnfoldAdminSelectMultipleWidget,
     UnfoldAdminSelectWidget,
     UnfoldAdminSplitDateTimeVerticalWidget,
@@ -71,6 +77,38 @@ class Media:
         }
 
 
+class CheckboxForm(forms.Form):
+    field = MultipleChoiceField
+    widget = UnfoldAdminCheckboxSelectMultiple
+
+    def __init__(
+        self,
+        name: str,
+        label: str,
+        choices: tuple,
+        *args,
+        **kwargs,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+
+        self.fields[name] = self.field(
+            label=label,
+            required=False,
+            choices=choices,
+            widget=self.widget,
+        )
+
+
+class RadioForm(CheckboxForm):
+    field = ChoiceField
+    widget = UnfoldAdminRadioSelectWidget
+
+
+class HorizontalRadioForm(RadioForm):
+    horizontal = True
+    widget = UnfoldAdminRadioSelectWidget(radio_style=HORIZONTAL)
+
+
 class DropdownForm(forms.Form):
     widget = UnfoldAdminSelectWidget(
         attrs={

src/unfold/static/unfold/css/styles.css

@@ -74,21 +74,23 @@
                         {% include cl.model_admin.list_before_template %}
                     {% endif %}
 
-                    <div class="flex flex-col gap-4 mb-4  sm:flex-row empty:hidden lg:border lg:border-base-200 lg:dark:border-base-800 lg:-mb-8 lg:p-3 lg:pb-11 lg:rounded-t">
-                        {% block search %}
-                            {% search_form cl %}
-                        {% endblock %}
+                    {% spaceless %}
+                        <div class="flex flex-col gap-4 mb-4  sm:flex-row empty:hidden lg:border lg:border-base-200 lg:dark:border-base-800 lg:-mb-8 lg:p-3 lg:pb-11 lg:rounded-t">
+                            {% block search %}
+                                {% search_form cl %}
+                            {% endblock %}
 
-                        {% block filters %}
-                            {% if cl.has_filters %}
-                                <a class="{% if cl.has_active_filters %}bg-primary-600 border-primary-600 text-white{% else %}bg-white border-base-200 hover:text-primary-600 dark:bg-base-900 dark:border-base-700 dark:hover:text-primary-500{% endif %} border cursor-pointer flex font-medium gap-2 group items-center px-3 py-2 rounded shadow-sm text-sm lg:ml-auto md:mt-0 {% if not cl.model_admin.list_filter_sheet %}2xl:hidden{% endif %}" x-on:click="filterOpen = true" x-on:keydown.escape.window="filterOpen = false">
-                                    {% trans "Filters" %}
+                            {% block filters %}
+                                {% if cl.has_filters %}
+                                    <a class="{% if cl.has_active_filters %}bg-primary-600 border-primary-600 text-white{% else %}bg-white border-base-200 hover:text-primary-600 dark:bg-base-900 dark:border-base-700 dark:hover:text-primary-500{% endif %} border cursor-pointer flex font-medium gap-2 group items-center px-3 py-2 rounded shadow-sm text-sm lg:ml-auto md:mt-0 {% if not cl.model_admin.list_filter_sheet %}2xl:hidden{% endif %}" x-on:click="filterOpen = true" x-on:keydown.escape.window="filterOpen = false">
+                                        {% trans "Filters" %}
 
-                                    <span class="material-symbols-outlined md-18 ml-auto">filter_list</span>
-                                </a>
-                            {% endif %}
-                        {% endblock %}
-                    </div>
+                                        <span class="material-symbols-outlined md-18 ml-auto">filter_list</span>
+                                    </a>
+                                {% endif %}
+                            {% endblock %}
+                        </div>
+                    {% endspaceless %}
 
                     <form id="changelist-form" class="group" method="post"{% if cl.formset and cl.formset.is_multipart %} enctype="multipart/form-data"{% endif %} novalidate>
                         {% csrf_token %}