Fixed #21528 -- Added note about filtering form field's queryset based on instance to admin docs.

2 files changed, 14 insertions, 0 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index ddd2cfbb67..d532d7b337 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -1812,6 +1812,18 @@ templates used by the :class:`ModelAdmin` views:
     This uses the ``HttpRequest`` instance to filter the ``Car`` foreign key
     field to only display the cars owned by the ``User`` instance.
 
+    For more complex filters, you can use ``ModelForm.__init__()`` method to
+    filter based on an ``instance`` of your model (see
+    :ref:`fields-which-handle-relationships`). For example::
+
+        class CountryAdminForm(forms.ModelForm):
+            def __init__(self, *args, **kwargs):
+                super().__init__(*args, **kwargs)
+                self.fields['capital'].queryset = self.instance.cities.all()
+
+        class CountryAdmin(admin.ModelAdmin):
+            form = CountryAdminForm
+
 .. method:: ModelAdmin.formfield_for_manytomany(db_field, request, **kwargs)
 
     Like the ``formfield_for_foreignkey`` method, the
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index d7f3ca17a2..bd80f939e5 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -1174,6 +1174,8 @@ Slightly complex built-in ``Field`` classes
     If no ``input_time_formats`` argument is provided, the default input formats
     for :class:`TimeField` are used.
 
+.. _fields-which-handle-relationships:
+
 Fields which handle relationships
 =================================