Fixed #14370 -- Allowed using a Select2 widget for ForeignKey and ManyToManyField in the admin.

Thanks Florian Apolloner and Tim Graham for review and
contributing to the patch.

4 files changed, 80 insertions, 4 deletions

diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt
index b4d1fd4089..0ca1d176f4 100644
--- a/docs/ref/checks.txt
+++ b/docs/ref/checks.txt
@@ -527,6 +527,15 @@ with the admin site:
 * **admin.E034**: The value of ``readonly_fields`` must be a list or tuple.
 * **admin.E035**: The value of ``readonly_fields[n]`` is not a callable, an
   attribute of ``<ModelAdmin class>``, or an attribute of ``<model>``.
+* **admin.E036**: The value of ``autocomplete_fields`` must be a list or tuple.
+* **admin.E037**: The value of ``autocomplete_fields[n]`` refers to
+  ``<field name>``, which is not an attribute of ``<model>``.
+* **admin.E038**: The value of ``autocomplete_fields[n]`` must be a foreign
+  key or a many-to-many field.
+* **admin.E039**: An admin for model ``<model>`` has to be registered to be
+  referenced by ``<modeladmin>.autocomplete_fields``.
+* **admin.E040**: ``<modeladmin>`` must define ``search_fields``, because
+  it's referenced by ``<other_modeladmin>.autocomplete_fields``.
 
 ``ModelAdmin``
 ~~~~~~~~~~~~~~
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 51f9e70b73..965150cc3a 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -519,11 +519,13 @@ subclass::
         If you want to use a custom widget with a relation field (i.e.
         :class:`~django.db.models.ForeignKey` or
         :class:`~django.db.models.ManyToManyField`), make sure you haven't
-        included that field's name in ``raw_id_fields`` or ``radio_fields``.
+        included that field's name in ``raw_id_fields``, ``radio_fields``, or
+        ``autocomplete_fields``.
 
         ``formfield_overrides`` won't let you change the widget on relation
-        fields that have ``raw_id_fields`` or ``radio_fields`` set. That's
-        because ``raw_id_fields`` and ``radio_fields`` imply custom widgets of
+        fields that have ``raw_id_fields``, ``radio_fields``, or
+        ``autocomplete_fields`` set. That's because ``raw_id_fields``,
+        ``radio_fields``, and ``autocomplete_fields`` imply custom widgets of
         their own.
 
 .. attribute:: ModelAdmin.inlines
@@ -1071,6 +1073,58 @@ subclass::
     Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
     ``choices`` set.
 
+.. attribute:: ModelAdmin.autocomplete_fields
+
+    .. versionadded:: 2.0
+
+    ``autocomplete_fields`` is a list of ``ForeignKey`` and/or
+    ``ManyToManyField`` fields you would like to change to `Select2
+    <https://select2.org/>`_ autocomplete inputs.
+
+    By default, the admin uses a select-box interface (``<select>``) for fields
+    that are . Sometimes you don't want to incur the overhead of selecting all
+    the related instances to display in the dropdown.
+
+    The Select2 input looks similar to the default input but comes with a
+    search feature that loads the options asynchronously. This is faster and
+    more user-friendly if the related model has many instances.
+
+    You must define :attr:`~ModelAdmin.search_fields` on the related object's
+    ``ModelAdmin`` because the autocomplete search uses it.
+
+    Ordering and pagination of the results are controlled by the related
+    ``ModelAdmin``'s :meth:`~ModelAdmin.get_ordering` and
+    :meth:`~ModelAdmin.get_paginator` methods.
+
+    In the following example, ``ChoiceAdmin`` has an autocomplete field for the
+    ``ForeignKey`` to the ``Question``. The results are filtered by the
+    ``question_text`` field and ordered by the ``date_created`` field::
+
+        class QuestionAdmin(admin.ModelAdmin):
+            ordering = ['date_created']
+            search_fields = ['question_text']
+
+        class ChoiceAdmin(admin.ModelAdmin):
+            autocomplete_fields = ['question']
+
+    .. admonition:: Performance considerations for large datasets
+
+        Ordering using :attr:`ModelAdmin.ordering` may cause performance
+        problems as sorting on a large queryset will be slow.
+
+        Also, if your search fields include fields that aren't indexed by the
+        database, you might encounter poor performance on extremely large
+        tables.
+
+        For those cases, it's a good idea to write your own
+        :func:`ModelAdmin.get_search_results` implementation using a
+        full-text indexed search.
+
+        You may also want to change the ``Paginator`` on very large tables
+        as the default paginator always performs a ``count()`` query.
+        For example, you could override the default implementation of the
+        ``Paginator.count`` property.
+
 .. attribute:: ModelAdmin.raw_id_fields
 
     By default, Django's admin uses a select-box interface (<select>) for
@@ -1431,6 +1485,15 @@ templates used by the :class:`ModelAdmin` views:
     pre- or post-save operations for objects related to the parent. Note
     that at this point the parent object and its form have already been saved.
 
+.. method:: ModelAdmin.get_autocomplete_fields(request)
+
+    .. versionadded:: 2.0
+
+    The ``get_readonly_fields()`` method is given the ``HttpRequest`` and is
+    expected to return a ``list`` or ``tuple`` of field names that will be
+    displayed with an autocomplete widget as described above in the
+    :attr:`ModelAdmin.autocomplete_fields` section.
+
 .. method:: ModelAdmin.get_readonly_fields(request, obj=None)
 
     The ``get_readonly_fields`` method is given the ``HttpRequest`` and the
diff --git a/docs/releases/2.0.txt b/docs/releases/2.0.txt
index fd9cf8dfd3..b45e494800 100644
--- a/docs/releases/2.0.txt
+++ b/docs/releases/2.0.txt
@@ -66,7 +66,10 @@ Minor features
 :mod:`django.contrib.admin`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* ...
+* The new :attr:`.ModelAdmin.autocomplete_fields` attribute and
+  :meth:`.ModelAdmin.get_autocomplete_fields` method allow using an
+  `Select2 <https://select2.org>`_ search widget for ``ForeignKey`` and
+  ``ManyToManyField``.
 
 :mod:`django.contrib.admindocs`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist
index 4cfdc65906..08b70f4ac3 100644
--- a/docs/spelling_wordlist
+++ b/docs/spelling_wordlist
@@ -27,6 +27,7 @@ attr
 auth
 autoclobber
 autocommit
+autocomplete
 autocompletion
 autodetect
 autodetectable