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

Backport of d38c34119e91a533c797098f150abe99b5ee2fd8 from master

2 files changed, 14 insertions, 0 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 4a4450175f..e2a6c002e6 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -1802,6 +1802,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 58db957512..60fa0bbce6 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
 =================================