From e182723371e0e5838339953657c19cbcecfd39f7 Mon Sep 17 00:00:00 2001
From: Matt Westcott <matt@west.co.tt>
Date: Thu, 30 Apr 2020 17:56:36 +0100
Subject: [PATCH] More detailed docstring for FilteredSelect; also tweak it to
 accept filter_values as an actual list rather than a comma-delimited string

---
 wagtail/admin/filters.py                 |  3 +--
 wagtail/admin/widgets/filtered_select.py | 16 ++++++++++++----
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/wagtail/admin/filters.py b/wagtail/admin/filters.py
index 3d5174a815..0f16c19a88 100644
--- a/wagtail/admin/filters.py
+++ b/wagtail/admin/filters.py
@@ -55,8 +55,7 @@ class FilteredModelChoiceField(django_filters.fields.ModelChoiceField):
         if callable(queryset):
             queryset = queryset()
 
-        ids = queryset.values_list('pk', flat=True)
-        return ','.join([str(id) for id in ids])
+        return queryset.values_list('pk', flat=True)
 
 
 class FilteredModelChoiceFilter(django_filters.ModelChoiceFilter):
diff --git a/wagtail/admin/widgets/filtered_select.py b/wagtail/admin/widgets/filtered_select.py
index e742d2df37..10a77557ee 100644
--- a/wagtail/admin/widgets/filtered_select.py
+++ b/wagtail/admin/widgets/filtered_select.py
@@ -5,9 +5,17 @@ from wagtail.admin.staticfiles import versioned_static
 
 class FilteredSelect(forms.Select):
     """
-    A select box variant that adds 'data-' attributes to the <select> and <option> elements
-    to allow the options to be dynamically filtered by another select box.
-    See wagtailadmin/js/filtered-select.js for an example of how these attributes are configured.
+    A select box where the options are shown and hidden dynamically in response to another
+    form field whose HTML `id` is specified in `filter_field`.
+
+    The `choices` list accepts entries of the form `(value, label, filter_values)` in addition
+    to the standard `(value, label)` tuples, where `filter_values` is a list of values;
+    whenever `filter_field` is set to a non-empty value, only the items with that value in their
+    `filter_values` list are shown.
+
+    filter_field and filter_values are inserted as 'data-' attributes on the rendered HTML, where
+    they are picked up by the Javascript behaviour code -
+    see wagtailadmin/js/filtered-select.js for an example of how these attributes are configured.
     """
 
     def __init__(self, attrs=None, choices=(), filter_field=''):
@@ -74,7 +82,7 @@ class FilteredSelect(forms.Select):
             name, value, label, selected, index, subindex=subindex, attrs=attrs
         )
         if filter_value is not None:
-            option['attrs']['data-filter-value'] = filter_value
+            option['attrs']['data-filter-value'] = ','.join([str(val) for val in filter_value])
 
         return option