Fixed #32539 -- Added toggleable facet filters to ModelAdmin.

Thanks Carlton Gibson, Simon Willison, David Smith, and Mariusz
Felisiak for reviews.

5 files changed, 67 insertions, 0 deletions

diff --git a/docs/intro/_images/admin13t.png b/docs/intro/_images/admin13t.png
index 3fed5f1985..de20217f2d 100644
--- a/docs/intro/_images/admin13t.png
+++ b/docs/intro/_images/admin13t.png
diff --git a/docs/ref/contrib/admin/_images/list_filter.png b/docs/ref/contrib/admin/_images/list_filter.png
index 8b6a5a7a54..35d30b8381 100644
--- a/docs/ref/contrib/admin/_images/list_filter.png
+++ b/docs/ref/contrib/admin/_images/list_filter.png
diff --git a/docs/ref/contrib/admin/filters.txt b/docs/ref/contrib/admin/filters.txt
index ca8881a645..fc70a1d6b2 100644
--- a/docs/ref/contrib/admin/filters.txt
+++ b/docs/ref/contrib/admin/filters.txt
@@ -210,3 +210,14 @@ It is possible to specify a custom template for rendering a list filter::
 
 See the default template provided by Django (``admin/filter.html``) for a
 concrete example.
+
+.. _facet-filters:
+
+Facets
+======
+
+.. versionadded:: 5.0
+
+By default, counts for each filter, known as facets, can be shown by toggling
+on via the admin UI. These counts will update according to the currently
+applied filters. See :attr:`ModelAdmin.show_facets` for more details.
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 67007baef2..aa3044e66b 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -1002,6 +1002,54 @@ subclass::
     editing, or deleting an object. You can have filters cleared by setting
     this attribute to ``False``.
 
+.. attribute:: ModelAdmin.show_facets
+
+    .. versionadded:: 5.0
+
+    Controls whether facet counts are displayed for filters in the admin
+    changelist. Defaults to :attr:`.ShowFacets.ALLOW`.
+
+    When displayed, facet counts update in line with currently applied filters.
+
+    .. class:: ShowFacets
+
+        .. versionadded:: 5.0
+
+        Enum of allowed values for :attr:`.ModelAdmin.show_facets`.
+
+        .. attribute:: ALWAYS
+
+            Always show facet counts.
+
+        .. attribute:: ALLOW
+
+            Show facet counts when the ``_facets`` query string parameter is
+            provided.
+
+        .. attribute:: NEVER
+
+            Never show facet counts.
+
+    Set ``show_facets`` to the desired :class:`.ShowFacets` value. For example,
+    to always show facet counts without needing to provide the query
+    parameter::
+
+        from django.contrib import admin
+
+
+        class MyModelAdmin(admin.ModelAdmin):
+            ...
+            # Have facets always shown for this model admin.
+            show_facets = admin.ShowFacets.ALWAYS
+
+    .. admonition:: Performance considerations with facets
+
+        Enabling facet filters will increase the number of queries on the admin
+        changelist page in line with the number of filters. These queries may
+        cause performance problems, especially for large datasets. In these
+        cases it may be appropriate to set ``show_facets`` to
+        :attr:`.ShowFacets.NEVER` to disable faceting entirely.
+
 .. attribute:: ModelAdmin.radio_fields
 
     By default, Django's admin uses a select-box interface (<select>) for
diff --git a/docs/releases/5.0.txt b/docs/releases/5.0.txt
index 84689f223d..254654eb7d 100644
--- a/docs/releases/5.0.txt
+++ b/docs/releases/5.0.txt
@@ -37,6 +37,14 @@ compatible with Django 5.0.
 What's new in Django 5.0
 ========================
 
+Facet filters in the admin
+--------------------------
+
+Facet counts are now show for applied filters in the admin changelist when
+toggled on via the UI. This behavior can be changed via the new
+:attr:`.ModelAdmin.show_facets` attribute. For more information see
+:ref:`facet-filters`.
+
 Minor features
 --------------